Add Documentation section to style guide #1062
Conversation
doc/topics/style-guide.md
Outdated
|
|
||
| - Put comments **above** the thing being documented (instead of inline). | ||
| - Use the `/** ... */` comment style (instead of `///`). | ||
| - Use `\ref` when referencing other classes, functions, etc. in the Cesium Native API. |
There was a problem hiding this comment.
Would @link be a better choice? We seem to use both interchangeably and @link is more consistent with JSDoc.
There was a problem hiding this comment.
We initially were using @link, but I think it wasn't actually working when we generated documentation? 😦 hence #800
There was a problem hiding this comment.
Technically @ref and @link aren't interchangeable. \ref can have an optional link text specified after the ref name, like @ref CesiumUtility::Uri "URI parsing". Whereas @link is supposed to be paired with @endlink, like @link CesiumUtility::Uri URI parsing @endlink. Because we use the JSDoc inline link tag, {@link name}, Doxygen somehow seems to understand this and doesn't require us to use @endlink. But I'd prefer to use the suggested Doxygen syntax rather than this JSDoc compatibility feature.
There was a problem hiding this comment.
@azrogers do you know if @ref works the same as \ref? If so, I think we should stick with @ref so it matches the rest of the tags we use
There was a problem hiding this comment.
@j9liu @ref and \ref work the same. The @ and \ are interchangeable prefixes (I accidentally used \ref where I meant to use @ref in that comment). Personally, I like to use @ in the directives at the start of the line and \ for the directives in the middle of the line (like @brief Some text with a \ref Item tag) to distinguish between inline and non-inline tags. But that's just me and it's probably best if we keep it consistent instead.
| - `@details`: Use for lengthier explanations, after `@brief`. | ||
| - `@tparam`: Describe template parameters. | ||
| - `@param`: Denote and describe function parameters. | ||
| - `@returns`: Describe the return value of a non-`void` function. |
There was a problem hiding this comment.
I sometimes see @return (singular). I like the plural version more.
I was writing this as part of CesiumGS/cesium-unreal#1541, but since we're using Doxygen for both Native and Unreal, I figured I should move the section here.
This encapsulates what we do for public API documentation, just formally writing it down for the record.