Difference between revisions of "Doxygen"
From GnuCash
(→Creating the Source Documentation: Update to Gnucash 3.x) |
m (→Improving the Source Documentation: typo) |
||
| Line 34: | Line 34: | ||
* @{ | * @{ | ||
* @file | * @file | ||
| − | * @brief <A brief | + | * @brief <A brief description> |
* @author Copyright (C) <year> <name> <email> | * @author Copyright (C) <year> <name> <email> | ||
*/ | */ | ||
Revision as of 14:50, 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.
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
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>
*/
where <module> is usually the name of the directory.
Links
- GnuCash Doxygen Source Documentation
- Doxygen Documentation http://www.stack.nl/~dimitri/doxygen/index.html
