Doxygen

Doxygen is a 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.

This document gives a brief introduction to Doxygen, in particular how it is used with FreeCAD to document its sources. See the Doxygen Manual for the full information on its usage.

Doxygen with C++ code
The Getting started (Step 3) section of the Doxygen manual mentions the basic ways 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 function, 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 function, 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 (function, 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: documentation block 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. An alternative is using C++-style comments with an additional slash, so.

Second style: documentation block elsewhere
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 once in the 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 order to provide a description, or examples, of the code there. It is important that such files are correctly categorized in a group or namespace, for which Doxygen provides some auxiliary commands like, , and.

Example ; this file in FreeCAD's source tree gives a short explanation of the namespace.

Another example is the file. Before the implementation details of the methods, there is a documentation block that explains some details of the command framework of FreeCAD. It has various commands to structure the documentation. It even includes example code enclosed in a pair of and  keywords; when the file is processed by Doxygen this code example will be specially formatted to stand out. The keyword is used in several places to create links to named sections, subsections, pages or anchors elsewhere in the documentation. Similarly, the or  commands print "See also" and provide a link to other classes, functions, methods, variables, files or URLs. Example

Doxygen markup
All Doxygen documentation commands start with a backslash or an at-sign, at your preference. Normally the backslash is used, but occasionally the -sign is used to improve readability.

The commands can have one or more arguments. In the Doxygen manual the arguments are described as follows.
 * 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 \defgroup, and Grouping.
 * , see \ingroup, and Grouping.
 * , see \addtogroup, and Grouping.
 * , see \author; indicates the author of this piece of code.
 * , see \brief; briefly describes the function.
 * , see \file; documents a source or header file.
 * , see \page; puts the information in a separate page, not directly related to one specific class, file or member.
 * , see \package; indicates documentation for a Java package (but also used with Python).
 * , see \fn; documents a function.
 * , see \section; starts a section.
 * , see \subsection; starts a subsection.
 * , see \namespace; indicates information for a namespace.
 * , and, see \cond; defines a block to conditionally document or omit.
 * , see \a; displays the argument in italics for emphasis.
 * , see \param; indicates the parameter of a function.
 * , see \return; specifies the return value.
 * , see \sa; prints "See also".
 * , see \note; adds a paragraph to be used as a note.

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", that is, a pair of triple quotes   immediately after the class or function definition.
 * 2) The Doxygen way, putting comments before the class or function definition; in this case double pound signs  should start the comment, and then single pound signs can be used in subsequent lines.

Note:
 * The first option is preferred to comply with PEP8, PEP257 and most style guidelines for writing Python (see 1, 2). However, in this way Doxygen special commands don't work.
 * The second option isn't the traditional Python style, but it allows you to use Doxygen's special commands like and.

First style: Pythonic documentation
One docstring at the beginning to explain the general contents of this module (file). Then docstrings inside the function, class, and class method definitions. In this way, Doxygen will extract the comments and present them as is, without modification.

Second style: documentation block before the code
The documentation blocks start with a double pound sign. One at the beginning to explain the general content of this module (file). Then blocks before the function, class, and class method definitions, and one block after a variable. In this way, Doxygen will extract the documentation, recognize the special commands, , and , and format the information accordingly.

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 the section Special Commands in the manual for an explanation of each command.
 * 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 paragraph separators.
 * Links are automatically created for words corresponding to documented classes or functions. If the word is preceded by a percentage symbol, then this symbol is removed, and no link is created for the word.
 * Links are created when certain patterns are found in the text. See the section Automatic link generation in the manual for more information.
 * HTML tags that are in the documentation are interpreted and converted to LaTeX equivalents for the LaTeX output. See the section HTML Commands in the manual for an explanation of each supported HTML tag.

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