Red Hat Training

A Red Hat training course is available for Red Hat Enterprise Linux

Chapter 6. Documentation Tools

Red Hat Enterprise Linux 6 offers the Doxygen tool for generating documentation from source code and for writing standalone documentation.

6.1. Doxygen

Doxygen is a documentation tool that creates reference material both online in HTML and offline in Latex. It does this from a set of documented source files which makes it easy to keep the documentation consistent and correct with the source code.

6.1.1. Doxygen Supported Output and Languages

Doxygen has support for output in:
  • RTF (MS Word)
  • PostScript
  • Hyperlinked PDF
  • Compressed HTML
  • Unix man pages
Doxygen supports the following programming languages:
  • C
  • C++
  • C#
  • Objective -C
  • IDL
  • Java
  • VHDL
  • PHP
  • Python
  • Fortran
  • D

6.1.2. Getting Started

Doxygen uses a configuration file to determine its settings, therefore it is paramount that this be created correctly. Each project requires its own configuration file. The most painless way to create the configuration file is with the command doxygen -g config-file. This creates a template configuration file that can be easily edited. The variable config-file is the name of the configuration file. If it is committed from the command it is called Doxyfile by default. Another useful option while creating the configuration file is the use of a minus sign (-) as the file name. This is useful for scripting as it will cause Doxygen to attempt to read the configuration file from standard input (stdin).
The configuration file consists of a number of variables and tags, similar to a simple Makefile. For example:
TAGNAME = VALUE1 VALUE2...
For the most part these can be left alone but should it be required to edit them see the configuration page of the Doxygen documentation website for an extensive explanation of all the tags available. There is also a GUI interface called doxywizard. If this is the preferred method of editing then documentation for this function can be found on the Doxywizard usage page of the Doxygen documentation website.
There are eight tags that are useful to become familiar with.
INPUT

For small projects consisting mainly of C or C++ source and header files it is not required to change anything. However, if the project is large and consists of a source directory or tree, then assign the root directory or directories to the INPUT tag.

FILE_PATTERNS

File patterns (for example, *.cpp or *.h) can be added to this tag allowing only files that match one of the patterns to be parsed.

RECURSIVE

Setting this to yes will allow recursive parsing of a source tree.

EXCLUDE and EXCLUDE_PATTERNS

These are used to further fine-tune the files that are parsed by adding file patterns to avoid. For example, to omit all test directories from a source tree, use EXCLUDE_PATTERNS = */test/*.

EXTRACT_ALL

When this is set to yes, doxygen will pretend that everything in the source files is documented to give an idea of how a fully documented project would look. However, warnings regarding undocumented members will not be generated in this mode; set it back to no when finished to correct this.

SOURCE_BROWSER and INLINE_SOURCES

By setting the SOURCE_BROWSER tag to yes doxygen will generate a cross-reference to analyze a piece of software's definition in its source files with the documentation existing about it. These sources can also be included in the documentation by setting INLINE_SOURCES to yes.

6.1.3. Running Doxygen

Running doxygen config-file creates html, rtf, latex, xml, and / or man directories in whichever directory doxygen is started in, containing the documentation for the corresponding filetype.
HTML OUTPUT

This documentation can be viewed with a HTML browser that supports cascading style sheets (CSS), as well as DHTML and Javascript for some sections. Point the browser (for example, Mozilla, Safari, Konqueror, or Internet Explorer 6) to the index.html in the html directory.

LaTeX OUTPUT

Doxygen writes a Makefile into the latex directory in order to make it easy to first compile the Latex documentation. To do this, use a recent teTeX distribution. What is contained in this directory depends on whether the USE_PDFLATEX is set to no. Where this is true, typing make while in the latex directory generates refman.dvi. This can then be viewed with xdvi or converted to refman.ps by typing make ps. Note that this requires dvips.

There are a number of commands that may be useful. The command make ps_2on1 prints two pages on one physical page. It is also possible to convert to a PDF if a ghostscript interpreter is installed by using the command make pdf. Another valid command is make pdf_2on1. When doing this set PDF_HYPERLINKS and USE_PDFLATEX tags to yes as this will cause Makefile will only contain a target to build refman.pdf directly.
RTF OUTPUT

This file is designed to import into Microsoft Word by combining the RTF output into a single file: refman.rtf. Some information is encoded using fields but this can be shown by selecting all (CTRL+A or Edit -> select all) and then right-click and select the toggle fields option from the drop down menu.

XML OUTPUT

The output into the xml directory consists of a number of files, each compound gathered by doxygen, as well as an index.xml. An XSLT script, combine.xslt, is also created that is used to combine all the XML files into a single file. Along with this, two XML schema files are created, index.xsd for the index file, and compound.xsd for the compound files, which describe the possible elements, their attributes, and how they are structured.

MAN PAGE OUTPUT

The documentation from the man directory can be viewed with the man program after ensuring the manpath has the correct man directory in the man path. Be aware that due to limitations with the man page format, information such as diagrams, cross-references and formulas will be lost.

6.1.4. Documenting the Sources

There are three main steps to document the sources.
  1. First, ensure that EXTRACT_ALL is set to no so warnings are correctly generated and documentation is built properly. This allows doxygen to create documentation for documented members, files, classes and namespaces.
  2. There are two ways this documentation can be created:
    A special documentation block
    This comment block, containing additional marking so Doxygen knows it is part of the documentation, is in either C or C++. It consists of a brief description, or a detailed description. Both of these are optional. What is not optional, however, is the in body description. This then links together all the comment blocks found in the body of the method or function.

    Note

    While more than one brief or detailed description is allowed, this is not recommended as the order is not specified.
    The following will detail the ways in which a comment block can be marked as a detailed description:
    • C-style comment block, starting with two asterisks (*) in the JavaDoc style. 
      /**
 * ... documentation ...
 */
    • C-style comment block using the Qt style, consisting of an exclamation mark (!) instead of an extra asterisk. 
      /*!
 * ... documentation ...
 */
    • The beginning asterisks on the documentation lines can be left out in both cases if that is preferred.
    • A blank beginning and end line in C++ also acceptable, with either three forward slashes or two forward slashes and an exclamation mark. 
      ///
/// ... documentation
///
      or 
      //!
//! ... documentation ...
//!
    • Alternatively, in order to make the comment blocks more visible a line of asterisks or forward slashes can be used. 
      /////////////////////////////////////////////////
/// ... documentation ...
/////////////////////////////////////////////////
      or 
      /********************************************//**
 * ... documentation ...
 ***********************************************/
      Note that the two forwards slashes at the end of the normal comment block start a special comment block.
    There are three ways to add a brief description to documentation.
    • To add a brief description use \brief above one of the comment blocks. This brief section ends at the end of the paragraph and any further paragraphs are the detailed descriptions. 
      /*! \brief brief documentation.
 *         brief documentation.
 *
 *  detailed documentation.
 */
    • By setting JAVADOC_AUTOBRIEF to yes, the brief description will only last until the first dot followed by a space or new line. Consequentially limiting the brief description to a single sentence. 
      /** Brief documentation. Detailed documentation continues * from here.
 */
      This can also be used with the above mentioned three-slash comment blocks (///).
    • The third option is to use a special C++ style comment, ensuring this does not span more than one line. 
      /// Brief documentation.
/** Detailed documentation. */
      or 
      //! Brief documentation.

//! Detailed documentation //! starts here
      The blank line in the above example is required to separate the brief description and the detailed description, and JAVADOC_AUTOBRIEF must to be set to no.
    Examples of how a documented piece of C++ code using the Qt style can be found on the Doxygen documentation website
    It is also possible to have the documentation after members of a file, struct, union, class, or enum. To do this add a < marker in the comment block.\ 
    int var; /*!< detailed description after the member */
    Or in a Qt style as: 
    int var; /**< detailed description after the member */
    or 
    int var; //!< detailed description after the member
         //!<
    or 
    int var; ///< detailed description after the member
         ///<
    For brief descriptions after a member use: 
    int var; //!< brief description after the member
    or 
    int var; ///< brief description after the member
    Examples of these and how the HTML is produced can be viewed on the Doxygen documentation website
    Documentation at other places
    While it is preferable to place documentation in front of the code it is documenting, at times it is only possible to put it in a different location, especially if a file is to be documented; after all it is impossible to place the documentation in front of a file. This is best avoided unless it is absolutely necessary as it can lead to some duplication of information.
    To do this it is important to have a structural command inside the documentation block. Structural commands start with a backslash (\) or an at-sign (@) for JavaDoc and are followed by one or more parameters. 
    /*! \class Test
    \brief A test class.
    
    A more detailed description of class.
 */
    In the above example the command \class is used. This indicates that the comment block contains documentation for the class 'Test'. Others are:
    • \struct: document a C-struct
    • \union: document a union
    • \enum: document an enumeration type
    • \fn: document a function
    • \var: document a variable, typedef, or enum value
    • \def: document a #define
    • \typedef: document a type definition
    • \file: document a file
    • \namespace: document a namespace
    • \package: document a Java package
    • \interface: document an IDL interface
  3. Next, the contents of a special documentation block is parsed before being written to the HTML and / Latex output directories. This includes:
    1. Special commands are executed.
    2. Any white space and asterisks (*) are removed.
    3. Blank lines are taken as new paragraphs.
    4. Words are linked to their corresponding documentation. Where the word is preceded by a percent sign (%) the percent sign is removed and the word remains.
    5. Where certain patterns are found in the text, links to members are created. Examples of this can be found on the automatic link generation page on the Doxygen documentation website.
    6. When the documentation is for Latex, HTML tags are interpreted and converted to Latex equivalents. A list of supported HTML tags can be found on the HTML commands page on the Doxygen documentation website.

6.1.5. Resources

More information can be found on the Doxygen website.