Add comment metadata API autogeneration rules to C++ Style Guide.
- Dominant language
- HTML
- Stars
- 39.6k
- Forks
- 12.9k
- Avg merge
- 42m
- Merged PRs (30d)
- 15
Description
Rules for how comment metadata tags are to be formatted are missing. Doxygen tags should be defined as using \tag or @tag. I vote for @tag because it is more consistent with JavaDocs. Tags may be indented multiple different ways:
```c++
@tag Comment may be wrapped around
without indenting them.
@tag Or comment may be
wrapped indenting to align to the tag.
@tag Or they can be indented
one tab.
```
```c++
/* This may be the @brief section.
And this may be the @desc, but is it indented? Google Style Guide
pattern is to preserve horizontal and vertical space.
@param example Does the param section go before or after the @desc section?
*/ //< Does the closing comment tag go on the same line or the previous line?
//< The pattern again is to conserve vertical and horizontal space.
```
```c++
/* @brief Do we need to use @brief?
@param example Params after @breif and before @desc may not be neccissary and may
be more confusing.
@desc There is obviously an eyesore with the @desc section is not indented but
there is only 3 characters in the @breif line. For this reason, I vote
for not using @breif or @desc. Indenting the next comment line two
spaces works good.
*/
```
And what about @warning? The default style should be to include them if there is any thought in your mind someone may need a warning.
And don't forget about the @pre and @post
```c++
/* This is my own personal preference for @breif.
@return When you're looking up what a function does you care more about what
the return value is than the description. You must assume the developer knows
what the description is but the forgot what the return type was or did.
Preserve vertical and horizontal space and make the code more clear in order to
save developer time and create a more robust product.
@group ShouldAlwaysBeFirstBecauseItsADescriptor.
The @desc section looks best and preserves the most horizontal and vertical
space if the comments are not indented and @brief and @desc tags are implied
not explicit.
@pre Preconditions are part of the description and do not need a space to
separate them visually.
@post @pre should always go first and @post should always follow.
@note Followed by all of the other tags in any order.
@param param1 The params should be self-documenting so they should go at the
end.
@param param2 As long as we use this format, we don't need to indent to make
the comments more readable because we used minimal vertical whitespace for that.
```
Contributor guide
Assessment
This issue has not been assessed yet.