Doxygen

Developer(s)	Dimitri van Heesch
Initial release	26 October 1997 (1997-10-26)
Stable release	1.14.0  / 24 May 2025 (24 May 2025)
Repository	github.com/doxygen/doxygen
Written in	C++
Operating system	Cross-platform
Type	Documentation generator
License	GPLv2
Website	doxygen.nl

Doxygen (/ˈdɒksidʒən/ DOK-see-jən) is a documentation generator that works with many programming languages. It extracts information from specially-formatted source code comments and saves the information in one of various supported formats.

Doxygen supports static analysis of a codebase. It uses the parse tree parsed from the codebase to generate diagrams and charts of the code structure. It provides cross-referencing that a reader can use to refer back to the source code from the generated documentation.

Doxygen can be used in many programming contexts. It supports many languages including C, C++, C#, D, Fortran, IDL, Java, Objective-C, Perl, PHP, Python, and VHDL. It can run on many computers, including Unix-like, macOS, and Windows systems. It is free software, released under the terms of the GNU General Public License version 2 (GPLv2).

History

The first version of Doxygen borrowed code from an early version of DOC++, developed by Roland Wunderling and Malte Zöckler at Zuse Institute Berlin. Later, the Doxygen code was rewritten by Dimitri van Heesch.

Design

Like other documentation generators such as Javadoc, Doxygen extracts information from both the comment and the symbolic (non-comment) code. A comment is associated with a programming symbol due to its proximity to the symbol in the code. Markup in the comments allows for controlling inclusion and formatting of the resulting documentation.

Doxygen supports output in many formats including: HTML, CHM, RTF, PDF, LaTeX, PostScript and man page.

Doxygen can generate inheritance diagrams for C++ classes. For more advanced diagrams and graphs, Doxygen can use the "dot" tool from Graphviz.

Example code

The generic syntax of documentation comments is to start a comment with an extra asterisk (*) or exclamation (!) after the leading comment delimiter '/*':

/**
<A short one line description>

<Longer description>
<May span multiple lines or paragraphs as needed>

@param  someParameter  Description of method's or function's input or output parameter
@param  ...
@return Description of the return value
*/

All commands in the documentation start with a backslash (\) or an at-sign (@).

Many programmers like to mark the start of each line with space-asterisk-space, as follows, but that is not necessary.

/**
 * <A short one line description>
 *
 * <Longer description>
 * <May span multiple lines or paragraphs as needed>
 *
 * @param  someParameter  Description of method's or function's input or output parameter
 * @param  ...
 * @return Description of the return value
 */

Many programmers avoid using C-style comments and instead use C++ style single line comments. Doxygen accepts comments with an additional subsequent slash (/) or exclamation (!) as Doxygen comments.

/// <A short one line description>
///
/// <Longer description>
/// <May span multiple lines or paragraphs as needed>
///
/// @param  someParameter  Description of method's or function's input or output parameter
/// @param  ...
/// @return Description of the return value

//! <A short one line description>
//!
//! <Longer description>
//! <May span multiple lines or paragraphs as needed>
//!
//! @param  someParameter  Description of method's or function's input or output parameter
//! @param  ...
//! @return Description of the return value

The following illustrates how a C++ source file can be documented.

/**
 * @file
 * @brief  The header file of the Time class.
 * @author  John Doe <jdoe@example.com>
 * @version  1.0
 * @copyright  CC BY-SA or GFDL.
 * @sa  <a href="https://en.wikipedia.org/wiki/Wikipedia:Copyrights">Wikipedia:Copyrights - Wikipedia</a>
 */

/**
 * The time class represents a moment of time.
 *
 * @author John Doe
 */
class Time {
public:

    /**
     * Constructor that sets the time to a given value.
     *
     * @param timeMillis A number of milliseconds passed since Jan 1, 1970.
     */
    explicit Time(long long timeMillis) {
        // the code
    }

    /**
     * Get the current time.
     *
     * @return A time object set to the current time.
     */
    static Time now() {
        // the code
    }

private:
    long long m_timeMillis; ///< Milliseconds passed since Jan 1, 1970.
};

To put documentation after members, an additional < marker is required in the comment block.

An alternative approach for documenting parameters is shown below. It will produce the same documentation.

    /**
     * Constructor that sets the time to a given value.
     */
    explicit Time(long long timeMillis /**< A number of milliseconds passed since Jan 1, 1970. */
        )
    {
        // the code
    }

    /**
     * Constructor that sets the time to a given value.
     */
    explicit Time(long long timeMillis ///< A number of milliseconds passed since Jan 1, 1970.
        )
    {
        // the code
    }

Richer markup is also possible. For instance, add equations using LaTeX commands:

/**
 *
 * An inline equation @f$ e^{\pi i}+1 = 0 @f$
 *
 * A displayed equation: @f[ e^{\pi i}+1 = 0 @f]
 *
 */

Doxygen source and development

The Doxygen sources are currently hosted at GitHub, where the main developer, Dimitri van Heesch, contributes under the user name "doxygen". Doxygen is written in C++, and consists of around 300,000 source lines of code. For lexical analysis, the standard tool Lex (or its replacement Flex) is run via approximately 35,000 lines of lex script. The parsing tool Yacc (or its replacement Bison) is also used, but only for minor tasks; the bulk of language parsing is done by native C++ code. The build process is based on CMake and also involves some Python scripts.

See also

• Comparison of documentation generators
• API Writer
• Static program analysis

External links

• Official website