Difference between revisions of "Doxygen"

Revision as of 10:56, 27 November 2013

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://svn.gnucash.org/docs/HEAD/.

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.

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 */

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.

@@ Line 14: / Line 14: @@
 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==