Documenting FreeCAD's code

Below are a few remarks and notes about Doxygen usage for FreeCAD, gathered after examining and removing most of the warnings emited by Doxygen:

Pay attention to warnings emited by doxygen when building the doc. The item giving rise to the warning will be skipped and will not be documented !

Most of the problems you can run in are documented in the Troubleshooting page of doxygen documentation.

As a general rule, doxygen parser tries to identify unique names in the whole project. In particular, if the same identifier is found in several namespaces, you'll have to use full qualified names (with namespace_name:: prepended) to suppress warnings, in the code or with a header to the comment block. (see the various Workbenches classes as an example)

The parser tries to match declarations an definitions. You'll sometimes need to help a bit.

Albeit quite powerful, doxygen is not yet really clever with nested namespaces. Again you'll need to use fully qualified names.

The parsing is done on a file by file basis, and is not very happy with .inl files containing inline functions definitions, meant to be included from a header file inside a namespace block. Fix: take the include directive out of the namespace block in .h or .hpp file and put the whole .inl content in a namespace block.

Watch out for macros:
- Qualifiers like __dllexport or AppExport must be put in the PREDEFINED section of src/Doc/BuildDevDoc.cfg.in to be replaced by an empty string. It otherwise hinders doxygen names resolution.
- Macros which need to be defined for correct code coverage should also be listed in the PREDEFINED section, without the = sign (will be expanded as = 1)
- Function macros and macros which must be expanded should be listed in the EXPAND_AS_DEFINED section of src/Doc/BuildDevDoc.cfg.in
- Doxygen seems sensitive to the order of directories in input list, regarding macro definitions which must appear before they are used.

Templates specializations are not really well documented for now and generate warnings. Better skip the specialized redefinitions enclosing them in a /// @cond DOXERR /// @endcond block.

JAVADOC_AUTOBRIEF is enabled, so more brief comments are generated, with or without explicit \brief tag.