FreeCAD

1
/** \page doctips Documenting FreeCAD's code
2

3
Below are a few remarks and notes about Doxygen usage for FreeCAD,
4
gathered after examining and removing most of the warnings emitted
5
by Doxygen.  For information on (re)building the source docs, see
6
\ref makingdocs
7

8
- Pay attention to warnings emitted by doxygen when building the doc.
9
  The item giving rise to the warning will be skipped and will not be
10
  documented !
11

12
- Most of the problems you can run in are documented in the Troubleshooting
13
  page of doxygen documentation.
14

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

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

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

28
- 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. 
29
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.
30

31
- Watch out for macros:
32
   - 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.
33
   - 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)
34
   - Function macros and macros which must be expanded should be listed in the EXPAND_AS_DEFINED section of src/Doc/BuildDevDoc.cfg.in
35
   - Doxygen seems sensitive to the order of directories in input list,
36
regarding macro definitions which must appear before they are used.
37

38
- 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.
39

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

42
\date 2010
43
\author Pascal Moucheront (midgetfc at free dot fr)
44
*/
45