Doxygen

Background

From the Doxygen help file: For members, classes and namespaces there are basically two options:

1. Place a special documentation block in front of the declaration or definition of the member, class or namespace. For file, class and namespace members it is also allowed to place the documentation directly after the member.

   See section Special comment blocks to learn more about special documentation blocks.

2. Place a special documentation block somewhere else (another file or another location) and put a structural command in the documentation block. A structural command links a documentation block to a certain entity that can be documented (e.g. a member, class, namespace or file).

   See section Documentation at other places to learn more about structural commands.

Note:

• The advantage of the first option is that you do not have to repeat the name of the entity.
• Files can only be documented using the second option, since there is no way to put a documentation block before a file. Of course, file members (functions, variables, typedefs, defines) do not need an explicit structural command; just putting a special documentation block in front or behind them will work fine.

Explanation of doxygen markup

• \addtogroup \addtogroup <name> [(title)]
• \brief \brief { brief description }
• \param \param [(dir)] <parameter-name> { parameter description }
• \return \return { description of the return value } (syn. \returns)
• \note \note { text }

FreeCAD doxygen

FC doxygen formatting

The FC project has chosen the following method for it's doxygen comment blocks: As it's special char of choice

• \note ex. \note added in FreeCAD 0.17

Note: Please also read: https://github.com/FreeCAD/FreeCAD/blob/master/src/Doc/doctips.dox