Doxygen

Doxygen is a very popular tool for generating documentation from annotated C++ sources, but it also supports other popular programming languages such as C#, PHP, Java, and Python. Visit Doxygen website to learn more about the system.

Head to the Manual to start using Doxygen with source files.

Introduction
The Doxygen getting started section mentions some characteristics of documenting the sources.

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 these 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.

The special documentation block starts like a C-style comment but has an additional asterisk, so. The block ends with a matching.

Note:
 * The advantage of the first option is that you do not have to repeat the name of the entity (member, class, or namespace), as Doxygen will analyze the code and extract the relevant information.
 * 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 before or after them will work fine.

Parsing of comments
The text inside a special documentation block is parsed before it is written to the HTML and LaTeX output files. During parsing the following steps take place:
 * Markdown formatting is replaced by corresponding HTML or special commands.
 * The special commands inside the documentation are executed. See section Special Commands for an overview of all commands.
 * If a line starts with some whitespace followed by one or more asterisks and then optionally more whitespace, then all whitespace and asterisks are removed.
 * All resulting blank lines are treated as a paragraph separators. This saves you from placing new-paragraph commands yourself in order to make the generated documentation readable.
 * Links are created for words corresponding to documented classes. If the word is preceded by a -sign, then sign will be removed and the word won't be linked.
 * Links to members are created when certain patterns are found in the text. See section Automatic link generation for more information.
 * HTML tags that are in the documentation are interpreted and converted to \LaTeX equivalents for the \LaTeX output. See section HTML Commands for an overview of all supported HTML tags.

Example with the FreeCAD source code
The code in the file defines the Gui::Workbench class. Example code from

Doxygen markup
All Doxygen documentation commands start with a backslash or an at-sign, at your preference. In FreeCAD, C style comments are normally used, that is, a pair of and  to delimit the comment. In this case, the -sign is used in Doxygen commands to improve readability.

Some commands can have one or more arguments.
 * If braces are used the argument is a single word.
 * If braces are used the argument extends until the end of the line on which the command was found.
 * If  braces are used the argument extends until the next paragraph. Paragraphs are delimited by a blank line or by a section indicator.
 * If brackets are used the argument is optional.

Some of the most common keywords used in the FreeCAD documentation are
 * , see \addtogroup
 * , see \brief
 * , see \param
 * , see \return
 * , see \note

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: Please also read: https://github.com/FreeCAD/FreeCAD/blob/master/src/Doc/doctips.dox