Doxygen: the de facto Standard Tool for Generating Documentation from Annotated Code

LaTeX output

The generated $\mbox{\LaTeX}$ documentation must first be compiled by a $\mbox{\LaTeX}$ compiler (I use a recent teTeX distribution for Linux and MacOSX and MikTex for Windows). To simplify the process of compiling the generated documentation, doxygen writes a Makefile into the latex directory (on the Windows platform also a make.bat batch file is generated).

The contents and targets in the Makefile depend on the setting of USE_PDFLATEX. If it is disabled (set to NO), then typing make in the latex directory a dvi file called refman.dvi will be generated. This file can then be viewed using xdvi or converted into a PostScript file refman.ps by typing make ps (this requires dvips).

To put 2 pages on one physical page use make ps_2on1 instead. The resulting PostScript file can be send to a PostScript printer. If you do not have a PostScript printer, you can try to use ghostscript to convert PostScript into something your printer understands.

Conversion to PDF is also possible if you have installed the ghostscript interpreter; just type make pdf (or make pdf_2on1).

To get the best results for PDF output you should set the PDF_HYPERLINKS and USE_PDFLATEX tags to YES. In this case the Makefile will only contain a target to build refman.pdf directly.

XML output

The XML output consists of a structured dump of the information gathered by doxygen. Each compound (class/namespace/file/...) has its own XML file and there is also an index file called index.xml.

A file called combine.xslt XSLT script is also generated and can be used to combine all XML files into a single file.

Doxygen also generates two XML schema files index.xsd (for the index file) and compound.xsd (for the compound files). This schema file describes the possible elements, their attributes and how they are structured, i.e. it the describes the grammar of the XML files and can be used for validation or to steer XSLT scripts.

In the addon/doxmlparser directory you can find a parser library for reading the XML output produced by doxygen in an incremental way (see addon/doxmlparser/include/doxmlintf.h for the interface of the library).

Comment blocks for C-like languages (C/C++/C#/Objective-C/PHP/Java)*

For each entity in the code there are two (or in some cases three) types of descriptions, which together form the documentation for that entity; a brief description and detailed description, both are optional. For methods and functions there is also a third type of description, the so called in body description, which consists of the concatenation of all comment blocks found within the body of the method or function.

Having more than one brief or detailed description is allowed (but not recommended, as the order in which the descriptions will appear is not specified).

As the name suggest, a brief description is a short one-liner, whereas the detailed description provides longer, more detailed documentation. An in body description can also act as a detailed description or can describe a collection of implementation details. For the HTML output brief descriptions are also used to provide tooltips at places where an item is referenced.

There are several ways to mark a comment block as a detailed description:

• You can use the Javadoc style, which consist of a C-style comment block starting with two *'s, like this:

  /**
   * ... text ...
   */

• or you can use the Qt style and add an exclamation mark (!) after the opening of a C-style comment block, as shown in this example:

  /*!
   * ... text ...
   */

  In both cases the intermediate *'s are optional, so

  /*!
   ... text ...
  */

  is also valid.

• A third alternative is to use a block of at least two C++ comment lines, where each line starts with an additional slash or an exclamation mark. Here are examples of the two cases:

  Note that a blank line ends a documentation block in this case.

  ///
  /// ... text ...
  ///

  or

  //!
  //!... text ...
  //!

• Some people like to make their comment blocks more visible in the documentation. For this purpose you can use the following:

  /********************************************//**
   *  ... text
   ***********************************************/

  (note the 2 slashes to end the normal comment block and start a special comment block).

  or

  /////////////////////////////////////////////////
  /// ... text ...
  /////////////////////////////////////////////////

  or

  /************************************************
   *  ... text
   ***********************************************/

  as long as JAVADOC_BANNER = YES is used.

  /**
   * A brief history of JavaDoc-style (C-style) comments.
   *
   * This is the typical JavaDoc-style C-style comment. It starts with two
   * asterisks.
   *
   * @param theory Even if there is only one possible unified theory. it is just a
   *               set of rules and equations.
   */
  void cstyle( int theory );
  
  /*******************************************************************************
   * A brief history of JavaDoc-style (C-style) banner comments.
   *
   * This is the typical JavaDoc-style C-style "banner" comment. It starts with
   * a forward slash followed by some number, n, of asterisks, where n > 2. It's
   * written this way to be more "visible" to developers who are reading the
   * source code.
   *
   * Often, developers are unaware that this is not (by default) a valid Doxygen
   * comment block!
   *
   * However, as long as JAVADOC_BLOCK = YES is added to the Doxyfile, it will
   * work as expected.
   *
   * This style of commenting behaves well with clang-format.
   *
   * @param theory Even if there is only one possible unified theory. it is just a
   *               set of rules and equations.
   ******************************************************************************/
  void javadocBanner( int theory );
  
  /***************************************************************************//**
   * A brief history of Doxygen-style banner comments.
   *
   * This is a Doxygen-style C-style "banner" comment. It starts with a "normal"
   * comment and is then converted to a "special" comment block near the end of
   * the first line. It is written this way to be more "visible" to developers
   * who are reading the source code.
   * This style of commenting behaves poorly with clang-format.
   *
   * @param theory Even if there is only one possible unified theory. it is just a
   *               set of rules and equations.
   ******************************************************************************/
  void doxygenBanner( int theory );
  

For the brief description there are also several possibilities:

• One could use the \brief command with one of the above comment blocks. This command ends at the end of a paragraph, so the detailed description follows after an empty line.

  Here is an example:

  /*! \brief Brief description.
   *         Brief description continued.
   *
   *  Detailed description starts here.
   */

• If JAVADOC_AUTOBRIEF is set to YES in the configuration file, then using Javadoc style comment blocks will automatically start a brief description which ends at the first dot followed by a space or new line. Here is an example:

  /** Brief description which ends at this dot. Details follow
   *  here.
   */

  The option has the same effect for multi-line special C++ comments:

  /// Brief description which ends at this dot. Details follow
  /// here.

• A third option is to use a special C++ style comment which does not span more than one line. Here are two examples:

  /// Brief description.
  /** Detailed description. */

  pr

  //! Brief description.
  
  //! Detailed description
  //! starts here.

  Note the blank line in the last example, which is required to separate the brief description from the block containing the detailed description. The JAVADOC_AUTOBRIEF should also be set to NO for this case.

As you can see doxygen is quite flexible. If you have multiple detailed descriptions, like in the following example:

//! Brief description, which is
//! really a detailed description since it spans multiple lines.
/*! Another detailed description!
 */

They will be joined. Note that this is also the case if the descriptions are at different places in the code! In this case the order will depend on the order in which doxygen parses the code.

Unlike most other documentation systems, doxygen also allows you to put the documentation of members (including global functions) in front of the definition. This way the documentation can be placed in the source file instead of the header file. This keeps the header file compact, and allows the implementer of the members more direct access to the documentation. As a compromise the brief description could be placed before the declaration and the detailed description before the member definition.

int var; /*!< Detailed description after the member */

int var; /**< Detailed description after the member */

int var; //!< Detailed description after the member
         //!<

int var; ///< Detailed description after the member
         ///< 

int var; //!< Brief description after the member

int var; ///< Brief description after the member

void foo(int v /**< [in] docs for input parameter v. */);

/*! A test class */

class Afterdoc_Test
{
  public:
    /** An enum type.
     *  The documentation block cannot be put after the enum!
     */
    enum EnumType
    {
      int EVal1,     /**< enum value 1 */
      int EVal2      /**< enum value 2 */
    };
    void member();   //!< a member function.

  protected:
    int value;       /*!< an integer value */
};

//!  A test class.
/*!
  A more elaborate class description.
*/

class QTstyle_Test
{
  public:

    //! An enum.
    /*! More detailed enum description. */
    enum TEnum {
                 TVal1, /*!< Enum value TVal1. */
                 TVal2, /*!< Enum value TVal2. */
                 TVal3  /*!< Enum value TVal3. */
               }
         //! Enum pointer.
         /*! Details. */
         *enumPtr,
         //! Enum variable.
         /*! Details. */
         enumVar;

    //! A constructor.
    /*!
      A more elaborate description of the constructor.
    */
    QTstyle_Test();

    //! A destructor.
    /*!
      A more elaborate description of the destructor.
    */
   ~QTstyle_Test();

    //! A normal member taking two arguments and returning an integer value.
    /*!
      \param a an integer argument.
      \param s a constant character pointer.
      \return The test results
      \sa QTstyle_Test(), ~QTstyle_Test(), testMeToo() and publicVar()
    */
    int testMe(int a,const char *s);

    //! A pure virtual member.
    /*!
      \sa testMe()
      \param c1 the first argument.
      \param c2 the second argument.
    */
    virtual void testMeToo(char c1,char c2) = 0;

    //! A public variable.
    /*!
      Details.
    */
    int publicVar;

    //! A function variable.
    /*!
      Details.
    */
    int (*handler)(int a,int b);
};

/** Brief description (e.g.\ using only a few words). Details follow. */

/**
 *  A test class. A more elaborate class description.
 */

class Javadoc_Test
{
  public:

    /**
     * An enum.
     * More detailed enum description.
     */

    enum TEnum {
          TVal1, /**< enum value TVal1. */
          TVal2, /**< enum value TVal2. */
          TVal3  /**< enum value TVal3. */
         }
       *enumPtr, /**< enum pointer. Details. */
       enumVar;  /**< enum variable. Details. */

      /**
       * A constructor.
       * A more elaborate description of the constructor.
       */
      Javadoc_Test();

      /**
       * A destructor.
       * A more elaborate description of the destructor.
       */
     ~Javadoc_Test();

      /**
       * a normal member taking two arguments and returning an integer value.
       * @param a an integer argument.
       * @param s a constant character pointer.
       * @see Javadoc_Test()
       * @see ~Javadoc_Test()
       * @see testMeToo()
       * @see publicVar()
       * @return The test results
       */
       int testMe(int a,const char *s);

      /**
       * A pure virtual member.
       * @see testMe()
       * @param c1 the first argument.
       * @param c2 the second argument.
       */
       virtual void testMeToo(char c1,char c2) = 0;

      /**
       * a public variable.
       * Details.
       */
       int publicVar;

      /**
       * a function variable.
       * Details.
       */
       int (*handler)(int a,int b);
};

/*! \class Test
    \brief A test class.

    A more detailed class description.
*/

/*! \file */ 

/** @file */

/*! \file structcmd.h
    \brief A Documented file.

    Details.
*/

/*! \def MAX(a,b)
    \brief A macro that returns the maximum of \a a and \a b.

    Details.
*/

/*! \var typedef unsigned int UINT32
    \brief A type definition for a .

    Details.
*/

/*! \var int errno
    \brief Contains the last error code.

    \warning Not thread safe!
*/

/*! \fn int open(const char *pathname,int flags)
    \brief Opens a file descriptor.

    \param pathname The name of the descriptor.
    \param flags Opening flags.
*/

/*! \fn int close(int fd)
    \brief Closes the file descriptor \a fd.
    \param fd The descriptor to close.
*/

/*! \fn size_t write(int fd,const char *buf, size_t count)
    \brief Writes \a count bytes from \a buf to the filedescriptor \a fd.
    \param fd The descriptor to write to.
    \param buf The data buffer to write.
    \param count The number of bytes to write.
*/

/*! \fn int read(int fd,char *buf,size_t count)
    \brief Read bytes from a file descriptor.
    \param fd The descriptor to read from.
    \param buf The buffer to read into.
    \param count The number of bytes to read.
*/

#define MAX(a,b) (((a)>(b))?(a):(b))
typedef unsigned int UINT32;
int errno;
int open(const char *,int);
int close(int);
size_t write(int,const char *, size_t);
int read(int,char *,size_t);

/*! \file myscript.sh
 *  Look at this nice script:
 *  \verbinclude myscript.sh
 */

Comment blocks in Python*

...

<python code>

Comment blocks in VHDL*

For VHDL a comment normally start with --. Doxygen will extract comments starting with --!. There are only two types of comment blocks in VHDL; a one line --! comment representing a brief description, and a multi-line --! comment (where the --! prefix is repeated for each line) representing a detailed description.

Comments are always located in front of the item that is being documented with one exception: for ports the comment can also be after the item and is then treated as a brief description for the port.

Here is an example VHDL file with doxygen comments:

-------------------------------------------------------
--! @file
--! @brief 2:1 Mux using with-select
-------------------------------------------------------

--! Use standard library
library ieee;
--! Use logic elements
    use ieee.std_logic_1164.all;

--! Mux entity brief description

--! Detailed description of this
--! mux design element.
entity mux_using_with is
    port (
        din_0   : in  std_logic; --! Mux first input
        din_1   : in  std_logic; --! Mux Second input
        sel     : in  std_logic; --! Select input
        mux_out : out std_logic  --! Mux output
    );
end entity;

--! @brief Architecture definition of the MUX
--! @details More details about this mux element.
architecture behavior of mux_using_with is
begin
    with (sel) select
    mux_out <= din_0 when '0',
               din_1 when others;
end architecture;

As of VHDL 2008 it is also possible to use /‍* style comments. Doxygen will handle /‍* ... *‍/as plain comments and /‍*! ... *‍/ style comments as special comments to be parsed by doxygen.

To get proper looking output you need to set OPTIMIZE_OUTPUT_VHDL to YES in the configuration file. This will also affect a number of other settings. When they were not already set correctly doxygen will produce a warning telling which settings where overruled.

Comment blocks in Fortran*

When using doxygen for Fortran code you should set OPTIMIZE_FOR_FORTRAN to YES.

The parser tries to guess if the source code is fixed format Fortran or free format Fortran code. This may not always be correct. If not one should use EXTENSION_MAPPING to correct this. By setting EXTENSION_MAPPING = f=FortranFixed f90=FortranFree files with extension f are interpreted as fixed format Fortran code and files with extension f90 are interpreted as free format Fortran code.

For Fortran !> or !< starts a comment and !! or !> can be used to continue an one line comment into a multi-line comment.

Here is an example of a documented Fortran subroutine:

!> Build the restriction matrix for the aggregation
!! method.
!! @param aggr information about the aggregates
!! @todo Handle special case
subroutine intrestbuild(A,aggr,Restrict,A_ghost)
  implicit none
  Type(SpMtx), intent(in) :: A !< our fine level matrix
  Type(Aggrs), intent(in) :: aggr
  Type(SpMtx), intent(out) :: Restrict !< Our restriction matrix
  !...
end subroutine

As an alternative you can also use comments in fixed format code:

C> Function comment
C> another line of comment
      function a(i)
C> input parameter
        integer i
      end function A

Paragraphs

Even before doxygen had Markdown support it supported the same way of paragraph handling as Markdown: to make a paragraph you just separate consecutive lines of text by one or more blank lines.

An example:

Here is text for one paragraph.

We continue with more text in another paragraph.

Headers

Just like Markdown, doxygen supports two types of headers

Level 1 or 2 headers can be made as the follows

This is a level 1 header
========================

This is a level 2 header
------------------------

A header is followed by a line containing only ='s or -'s. Note that the exact amount of ='s or -'s is not important as long as there are at least two.

Alternatively, you can use #'s at the start of a line to make a header. The number of #'s at the start of the line determines the level (up to 6 levels are supported). You can end a header by any number of #'s.

Here is an example:

# This is a level 1 header

### This is level 3 header #######

Block quotes

Block quotes can be created by starting each line with one or more >'s, similar to what is used in text-only emails.

> This is a block quote
> spanning multiple lines

Lists and code blocks (see below) can appear inside a quote block. Quote blocks can also be nested.

Note that doxygen requires that you put a space after the (last) > character to avoid false positives, i.e. when writing

0  if OK\n
>1 if NOK

the second line will not be seen as a block quote.

Lists

Simple bullet lists can be made by starting a line with -, +, or *.

- Item 1

  More text for this item.

- Item 2
  + nested list item.
  + another nested item.
- Item 3

List items can span multiple paragraphs (if each paragraph starts with the proper indentation) and lists can be nested. You can also make a numbered list like so

1. First item.
2. Second item.

Make sure to also read Lists Extensions for doxygen specifics.

Code blocks

Preformatted verbatim blocks can be created by indenting each line in a block of text by at least 4 extra spaces

This a normal paragraph

    This is a code block

We continue with a normal paragraph again.

Doxygen will remove the mandatory indentation from the code block. Note that you cannot start a code block in the middle of a paragraph (i.e. the line preceding the code block must be empty).

See section Code Block Indentation for more info how doxygen handles indentation as this is slightly different than standard Markdown.

Horizontal rulers

A horizontal ruler will be produced for lines containing at least three or more hyphens, asterisks, or underscores. The line may also include any amount of whitespace.

Examples:

- - -
______

Note that using asterisks in comment blocks does not work. See Use of asterisks for details.

Note that when using hyphens and the previous line is not empty you have to use at least one whitespace in the sequence of hyphens otherwise it might be seen as a level 2 header (see Headers)

Emphasis

To emphasize a text fragment you start and end the fragment with an underscore or star. Using two stars or underscores will produce strong emphasis.

Examples:

*single asterisks*

 _single underscores_

 **double asterisks**

 __double underscores__

See section Emphasis and strikethrough limits for more info how doxygen handles emphasis / strikethrough spans slightly different than standard / Markdown GitHub Flavored Markdown.

Strikethrough

To strikethrough a text fragment you start and end the fragment with two tildes.

Examples:

~~double tilde~~

See section Emphasis and strikethrough limits for more info how doxygen handles emphasis / strikethrough spans slightly different than standard Markdown / GitHub Flavored Markdown.

Code spans

To indicate a span of code, you should wrap it in backticks (`). Unlike code blocks, code spans appear inline in a paragraph. An example:

Use the `printf()` function.

To show a literal backtick or single quote inside a code span use double backticks, i.e.

To assign the output of command `ls` to `var` use ``var=`ls```.
To assign the text 'text' to `var` use ``var='text'``.

See section Code Spans Limits for more info how doxygen handles code spans slightly different than standard Markdown.

Links

Doxygen supports both styles of make links defined by Markdown: inline and reference.

For both styles the link definition starts with the link text delimited by [square brackets].

Inline Links

For an inline link the link text is followed by a URL and an optional link title which together are enclosed in a set of regular parenthesis. The link title itself is surrounded by quotes.

Examples:

[The link text](http://example.net/)
[The link text](http://example.net/ "Link title")
[The link text](/relative/path/to/index.html "Link title")
[The link text](somefile.html) 

In addition doxygen provides a similar way to link a documented entity:

[The link text](@ref MyClass)

Reference Links

Instead of putting the URL inline, you can also define the link separately and then refer to it from within the text.

The link definition looks as follows:

[link name]: http://www.example.com "Optional title"

Instead of double quotes also single quotes or parenthesis can be used for the title part.

Once defined, the link looks as follows

[link text][link name]

If the link text and name are the same, also

[link name][]

or even

[link name]

can be used to refer to the link. Note that the link name matching is not case sensitive as is shown in the following example:

I get 10 times more traffic from [Google] than from
[Yahoo] or [MSN].

[google]: http://google.com/        "Google"
[yahoo]:  http://search.yahoo.com/  "Yahoo Search"
[msn]:    http://search.msn.com/    "MSN Search"

Link definitions will not be visible in the output.

Like for inline links doxygen also supports @ref inside a link definition:

[myclass]: @ref MyClass "My class"

Images*