Difference between revisions of "Doxygen"

From GnuCash
Jump to: navigation, search
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 is done and put online on a regular basis at [http://svn.gnucash.org/docs/HEAD/ http://svn.gnucash.org/docs/HEAD/].
+
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://svn.gnucash.org/docs/HEAD/ http://svn.gnucash.org/docs/HEAD/]
+
* 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

MAINT
the next minor bugfix and
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
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
MAINT
MASTER