6.7 How Doxygen Works
Doxygen understands the #include and #define preprocessor directives as
well as the syntax of C and C++. Thus, Doxygen can generate documentation using
just the existing syntactic elements of the source files, or one can supplement
the syntactic documentation using Section 6.8 "Special Documentation Blocks".
These special documentation blocks are just C or C++ comments with one or more
special tags added.
For structures, unions, functions, and global data, you have two documentation options:
Place a special documentation block in front of the declaration or definition. For enum, structure, and union members, you are also allowed to place documentation directly after a member. See Section 6.8 "Special Documentation Blocks", to learn more about special documentation blocks.
Place a special documentation block somewhere else (another file or 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 union, structure, function, or file).
The text inside a special documentation block is parsed before it is written to the output files. During parsing, the following steps take place:
The special commands inside the documentation block are executed.
If a line starts with some whitespace followed by one or more asterisks (*) and then optionally more whitespace, then all leading whitespace and asterisks are removed.
All resulting blank lines are treated as paragraph separators. This saves you from placing new-paragraph commands yourself in order to make the generated documentation readable.
Links to members are automatically created when certain patterns are found in the text. These patterns include: URLs and email addresses, names of documented classes and files, function and variable names, typedef, enum types, enum values, and defines.
HTML tags that are in the documentation are interpreted and converted to the proper equivalents for the selected output type.