HomeClusterLabs Projects

Doc: various: Drop doxygen structural commands

Description

Doc: various: Drop doxygen structural commands

We've been using "\enum" lines to document enums. However, this is not
required when the doxygen comment immediately precedes the definition.
In general, structural commands like this are discouraged, because they
create duplication.

See "Documentation at other places" at
https://www.doxygen.nl/manual/docblocks.html.

"The price you pay for not putting the documentation block directly
before (or after) an item is the need to put a structural command inside
the documentation block, which leads to some duplication of information.
So in practice you should avoid the use of structural commands unless
other requirements force you to do so.
...
Because each comment block in the example above contains a structural
command, all the comment blocks could be moved to another location or
input file (the source file for instance), without affecting the
generated documentation. The disadvantage of this approach is that
prototypes are duplicated, so all changes have to be made twice! Because
of this you should first consider if this is really needed, and avoid
structural commands if possible. I often receive examples that contain
\fn command in comment blocks which are place in front of a function.
This is clearly a case where the \fn command is redundant and will only
lead to problems."

Signed-off-by: Reid Wahl <nrwahl@protonmail.com>

Details

Provenance
nrwahl2Authored on Sat, Mar 8, 6:12 PM
Parents
rPd13aa3396312: Low: tools: Dry-run crm_resource --fail if CIB_file is set
Branches
Unknown
Tags
Unknown