Difference between revisions of "Doxygen"

From GnuCash
Jump to: navigation, search
(2 branches)
(Creating the Source Documentation: some links)
 
(11 intermediate revisions by 4 users not shown)
Line 1: Line 1:
[http://www.stack.nl/~dimitri/doxygen/index.html Doxygen] is the central point for source documentation at this moment (January 2011).
+
{| class="wikitable" style="margin: auto;"
 +
! scope="row"|Languages
 +
| [[{{PAGENAME}}|English]]
 +
| [[He/{{PAGENAME:דוקסיג'ן}}|עִברִית]]
 +
|}
 +
[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 http://code.gnucash.org/docs for both branches  
+
;Nightlies:This is done and put online on a regular basis at {{BuildServer}}/docs/ for both branches :
:;[http://code.gnucash.org/docs/MAINT/ MAINT]: the next minor bugfix and
+
:[{{BuildURL}}/docs/MAINT/ MAINT], the next minor bugfix and
:;[http://code.gnucash.org/docs/MASTER/ MASTER]: the next mayor release.
+
:[{{BuildURL}}/docs/MASTER/ MASTER], the next major release.
  
 
==Creating the Source Documentation==
 
==Creating the Source Documentation==
 +
See [[Building]] for the setup.
 +
Then it can be run on your local copy of the sources depending on your  [[Build Tools]]
 +
:;[[Build_Tools#Make|Make]]: <SyntaxHighlight lang="sh">
 +
make doc
 +
</SyntaxHighlight>
 +
:;[[Build_Tools#Ninja|Ninja]]: <SyntaxHighlight lang="sh">
 +
ninja doc
 +
</SyntaxHighlight>
  
It can be run on your local copy of the sources by
+
;Important:You need to have <tt>doxygen</tt> installed for this. Otherwise the target <tt>doc</tt> will not be available.
  
./configure --enable-doxygen --enable-html-docs
+
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>.
  make doc
 
  
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>.
+
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 <tt><</tt>, resulting in <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 <code><</code>, resulting in <tt>/**<</tt> or <tt>/*!<</tt>.
*Doxygen keywords begin with <tt>\</tt> or <tt>@</tt>.
+
*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>
+
* @addtogroup <module>
  * @{
+
* @{
  * @file
+
* @file
  * @brief <A brief sescription>
+
* @brief <A brief description>
  * @author Copyright (C) <year> <name> <email>
+
* @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:
* GnuCash Doxygen Source Documentation
+
:[{{BuildURL}}/docs/MAINT/ MAINT]
:[http://code.gnucash.org/docs/MAINT/ MAINT]
+
:[{{BuildURL}}/docs/MASTER/ MASTER]
:[http://code.gnucash.org/docs/MASTER/ MASTER]
+
;Doxygen:
* Doxygen Documentation [http://www.stack.nl/~dimitri/doxygen/index.html http://www.stack.nl/~dimitri/doxygen/index.html]
+
:[http://www.doxygen.nl/ Website]
 +
:[https://github.com/doxygen/doxygen Repository]
 +
[[Category:Development]][[Category:API]]

Latest revision as of 14:28, 1 December 2021

Languages English עִברִית

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.

Creating the Source Documentation

See Building for the setup. Then it can be run on your local copy of the sources depending on your Build Tools

Make
make doc
Ninja
ninja doc
Important
You need to have doxygen installed for this. Otherwise the target doc will not be available.

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 API Documentation
MAINT
MASTER
Doxygen
Website
Repository