Difference between revisions of "Doxygen"
From GnuCash
m (→Improving the Source Documentation: typo) |
(fix of several links; improve format) |
||
| Line 1: | Line 1: | ||
| − | [ | + | [https://en.wikipedia.org/wiki/Doxygen 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 | It is a software which extracts (special) comments from sourcecode to produce | ||
source documentation. | source documentation. | ||
| − | This is done and put online on a regular basis at | + | ;Nightlies:This is done and put online on a regular basis at {{BuildServer}}/docs/ for both branches : |
| − | : | + | :[{{BuildURL}}/docs/MAINT/ MAINT], the next minor bugfix and |
| − | : | + | :[{{BuildURL}}/docs/MASTER/ MASTER], the next major release. |
==Creating the Source Documentation== | ==Creating the Source Documentation== | ||
| Line 12: | Line 12: | ||
It can be run on your local copy of the sources by | It can be run on your local copy of the sources by | ||
<SyntaxHighlight lang="sh"> | <SyntaxHighlight lang="sh"> | ||
| − | + | make doc | |
</SyntaxHighlight> | </SyntaxHighlight> | ||
| − | This will populate < | + | This will populate <tt>${BUILDDIR}/libgnucash/doc</tt>. Problems will be logged there to <tt>doxygen.log</tt>. The HTML docs can be found in it's subdirectory <tt>html</tt>. |
| − | It's configuration gets created from < | + | It's configuration gets created from <tt>${SOURCEDIR}/libgnucash/doc/doxygen.cfg.in</tt>. |
==Doxygen Elements== | ==Doxygen Elements== | ||
*To mark a C style comment for Doxygen, it has to start with <tt>/**</tt> or <tt>/*!</tt>. | *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 < | + | *Usually the explaining comment should be in front of a declaration. If the comment is behind a member declaration, the next symbol should be <code><</code>, resulting in <tt>/**<</tt> or <tt>/*!<</tt>. |
| − | *Doxygen keywords begin with < | + | *Doxygen keywords begin with <code>\</code> or <code>@</code>. |
| − | *To document global objects, you must document the file in which they are defined: | + | *To document global objects, you must document the file in which they are defined:<syntaxhighlight lang="C"> |
/*! \file */ | /*! \file */ | ||
| − | :or | + | </syntaxhighlight> |
| + | :or<syntaxhighlight lang="C"> | ||
/** @file */ | /** @file */ | ||
| − | + | </syntaxhighlight> | |
==Improving the Source Documentation== | ==Improving the Source Documentation== | ||
| − | A header file of a public API should have the following Doxygen section: | + | A header file of a public API should have the following Doxygen section:<syntaxhighlight lang="C"> |
| − | + | /** | |
| − | + | * @addtogroup <module> | |
| − | + | * @{ | |
| − | + | * @file | |
| − | + | * @brief <A brief description> | |
| − | + | * @author Copyright (C) <year> <name> <email> | |
| − | + | */ | |
| − | where <module> is usually the name of the directory. | + | </syntaxhighlight> where <module> is usually the name of the directory. |
==Links== | ==Links== | ||
| − | + | ;GnuCash API Documentation: | |
| − | + | :[{{BuildURL}}/docs/MAINT/ MAINT] | |
| − | :[ | + | :[{{BuildURL}}/docs/MASTER/ MASTER] |
| − | :[ | + | ;Doxygen: |
| − | + | :[http://www.doxygen.nl/ Website] | |
| + | :[https://github.com/doxygen/doxygen Repository] | ||
Revision as of 15:39, 4 March 2020
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.
- Nightlies
- This is done and put online on a regular basis at code.gnucash.org/docs/ for both branches :
- MAINT, the next minor bugfix and
- MASTER, the next major release.
Contents
Creating the Source Documentation
It can be run on your local copy of the sources by
make doc
This will populate ${BUILDDIR}/libgnucash/doc. Problems will be logged there to doxygen.log. The HTML docs can be found in it's subdirectory html.
It's configuration gets created from ${SOURCEDIR}/libgnucash/doc/doxygen.cfg.in.
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 description>
* @author Copyright (C) <year> <name> <email>
*/
Links
- GnuCash API Documentation
- MAINT
- MASTER
- Doxygen
- Website
- Repository
