I like to make use of the fact that names can be documented in multiple places. In the header file, I write a brief description of the method, and document all its parameters – these are less likely to change than the implementation of the method itself, and if they do, then the function prototype … Read more
So why is API documentation written in such a way as to confuse perennial newbs / hackers / DIYers like myself? It’s really not meant to be written that way. I’ll agree there seems to be no ease of use across API documentations. However, there is a lot of cross over from older man style … Read more
Do you mean {@value #STATIC_FIELD}?
<ul> <li>Element</li> <ul> <li>Subelement…</li> You can pretty freely use HTML inside javadoc comments. Update: Because it came up, I tried <ul> <li>one</li> <ul> <li>one point one</li> </ul> </ul> and get one one point one I agree proper nesting is better.
There is a LaTeX3 project that has been going on for basically forever. In that sense, it is a successor to the current LaTeX2e. You forget/ignore the primary goal for TeX when it was created — “TeX is a new typesetting system intended for the creation of beautiful books”. The goal of TeX was typesetting, … Read more
@link and @code doesn’t exist in kDoc but can easily be replaced by Inline Markup. from KotlinDoc Linking to Elements Inline Markup For inline markup, KDoc uses the regular Markdown syntax, extended to support a shorthand syntax for linking to other elements in the code. Linking to Elements To link to another element (class, method, … Read more
I’ve been keeping the Dranger ffmpeg tutorials up to date here: https://github.com/mpenkov/ffmpeg-tutorial I’ve tried to keep the code changes minimal while fixing bugs and rewriting deprecated parts.
You can find it called Offset Aliases: A number of string aliases are given to useful common time series frequencies. We will refer to these aliases as offset aliases. Alias Description B business day frequency C custom business day frequency D calendar day frequency W weekly frequency M month end frequency SM semi-month end frequency … Read more
To avoid confusion: the term property has a specific meaning in python. What you’re talking about is what we call class attributes. Since they are always acted upon through their class, I find that it makes sense to document them within the class’ doc string. Something like this: class Albatross(object): “””A bird with a flight … Read more
You should document every exception that might be thrown by your code, including those in any methods that you might call. If the list gets a bit big, you might want to create your own exception type. Catch all the ones you might encounter within your method, wrap them in your exception, and throw that. … Read more