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.

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.

First style: before the code
Usually you'd want to document the code in the header file, just before the class declaration or function prototype. This keeps the declaration and documentation close to each other, so it's easy to update the latter one if the first one changes.

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

Second style: everywhere else
Alternatively, the documentation can be placed in another file (or in the same file at the top or bottom, or wherever), away from the class declaration or function prototype. In this case, you will have duplicated information, once in the actual source file, and a once in he documentation file.

First file, :

Second file, :

In this case the structural command is used to indicate which source file is being documented; a structural command  indicates that the following code is a function, and the command  is used to give a small description of this function.

This way of documenting a source file is useful if you just want to add documentation to your project without adding real code. When you place a comment block in a file with one of the following extensions, , or then Doxygen will parse the comments and build the appropriate documentation, but it will hide this auxiliary file from the file list.

The FreeCAD project adds several files ending in in many directories in the source code in order to provide a description or even examples of the code there. It is important that such files are correctly categorized in a group or namespace, for which Doxygen provides the auxiliary commands, ,.

For example, the code gives a short explanation of the  namespace. See the following code:

Another example is the file. Before the implementation details of the methods, it has a block of text which explains some details of the command framework of FreeCAD. It even includes example code which is introduced with the special command ; when the file is processed by Doxygen this code example will be specially formatted to stand out. See the following code:

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

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

Doxygen with Python code
Doxygen works best for statically typed languages like C++. However, it can also create documentation for Python files.

There are two ways to comment Python:
 * 1) The Pythonic way, using docstrings immediately after the class or function definition.
 * 2) The Doxygen way, putting comments before the class or function definition.

The first option is preferred to comply with PEP8 and most style guidelines for Python. However, in this way Doxygen doesn't recognize special commands.

The second option isn't the traditional Python style, but it allows you to use Doxygen's special commands.

Parsing of documentation blocks
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.

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