| /** \page doctips 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 emitted | |
| by Doxygen. For information on (re)building the source docs, see | |
| \ref makingdocs | |
| - Pay attention to warnings emitted 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. | |
| \date 2010 | |
| \author Pascal Moucheront (midgetfc at free dot fr) | |
| */ | |