Difference between revisions of "Doxygen"
From GnuCash
C.holtermann (talk | contribs) m (→Doxygen) |
m (fix typo) |
||
(3 intermediate revisions by one other user not shown) | |||
Line 2: | Line 2: | ||
It is a software which extracts (special) comments from sourcecode to produce | It is a software which extracts (special) comments from sourcecode to produce | ||
− | source documentation. It can be run on your local copy of the sources by | + | source documentation. |
+ | |||
+ | This is done and put online on a regular basis at http://code.gnucash.org/docs for both branches | ||
+ | :;[http://code.gnucash.org/docs/MAINT/ MAINT]: the next minor bugfix and | ||
+ | :;[http://code.gnucash.org/docs/MASTER/ MASTER]: the next major release. | ||
+ | |||
+ | ==Creating the Source Documentation== | ||
+ | |||
+ | It can be run on your local copy of the sources by | ||
./configure --enable-doxygen --enable-html-docs | ./configure --enable-doxygen --enable-html-docs | ||
make doc | make doc | ||
− | This | + | This will populate <tt>$BUILDDIR/src/doc</tt>. Problems will be logged there to <tt>doxygen.log</tt>. The HTML docs can be found in its subdir <tt>html</tt>. |
+ | |||
+ | ==Doxygen Elements== | ||
+ | *To mark a C style comment for Doxygen, it has to start with <tt>/**</tt> or <tt>/*!</tt>. | ||
+ | *Usually the explaining comment should be in front of a declaration. If the comment is behind a member declaration, the next symbol should be <tt><</tt>, resulting in <tt>/**<</tt> or <tt>/*!<</tt>. | ||
+ | *Doxygen keywords begin with <tt>\</tt> or <tt>@</tt>. | ||
+ | *To document global objects, you must document the file in which they are defined: | ||
+ | /*! \file */ | ||
+ | :or | ||
+ | /** @file */ | ||
+ | |||
+ | ==Improving the Source Documentation== | ||
+ | |||
+ | A header file of a public API should have the following Doxygen section: | ||
+ | /** | ||
+ | * @addtogroup <module> | ||
+ | * @{ | ||
+ | * @file | ||
+ | * @brief <A brief sescription> | ||
+ | * @author Copyright (C) <year> <name> <email> | ||
+ | */ | ||
+ | where <module> is usually the name of the directory. | ||
==Links== | ==Links== | ||
− | * GnuCash Doxygen Source Documentation [http:// | + | * GnuCash Doxygen Source Documentation |
+ | :[http://code.gnucash.org/docs/MAINT/ MAINT] | ||
+ | :[http://code.gnucash.org/docs/MASTER/ MASTER] | ||
* Doxygen Documentation [http://www.stack.nl/~dimitri/doxygen/index.html http://www.stack.nl/~dimitri/doxygen/index.html] | * Doxygen Documentation [http://www.stack.nl/~dimitri/doxygen/index.html http://www.stack.nl/~dimitri/doxygen/index.html] |
Revision as of 15:06, 27 July 2017
Doxygen is the central point for source documentation at this moment (January 2011).
It is a software which extracts (special) comments from sourcecode to produce source documentation.
This is done and put online on a regular basis at http://code.gnucash.org/docs for both branches
Contents
Creating the Source Documentation
It can be run on your local copy of the sources by
./configure --enable-doxygen --enable-html-docs make doc
This will populate $BUILDDIR/src/doc. Problems will be logged there to doxygen.log. The HTML docs can be found in its subdir html.
Doxygen Elements
- To mark a C style comment for Doxygen, it has to start with /** or /*!.
- Usually the explaining comment should be in front of a declaration. If the comment is behind a member declaration, the next symbol should be <, resulting in /**< or /*!<.
- Doxygen keywords begin with \ or @.
- To document global objects, you must document the file in which they are defined:
/*! \file */
- or
/** @file */
Improving the Source Documentation
A header file of a public API should have the following Doxygen section:
/** * @addtogroup <module> * @{ * @file * @brief <A brief sescription> * @author Copyright (C) <year> <name> <email> */
where <module> is usually the name of the directory.
Links
- GnuCash Doxygen Source Documentation
- Doxygen Documentation http://www.stack.nl/~dimitri/doxygen/index.html