Doxygen Explained

Doxygen
Developer:Dimitri van Heesch
Released:[1]
Latest Release Version:
Programming Language:C++
Operating System:Cross-platform
Genre:Documentation generator
License:GPLv2

Doxygen [2] is a documentation generator[3] [4] [5] [6] and static analysis tool for software source trees. When used as a documentation generator, Doxygen extracts information from specially-formatted comments within the code. When used for analysis, Doxygen uses its parse tree to generate diagrams and charts of the code structure. Doxygen can cross reference documentation and code, so that the reader of a document can easily refer to the actual code.

Doxygen is free software, released under the terms of the GNU General Public License version2 (GPLv2).

Design

Like Javadoc, Doxygen extracts documentation from source file comments. In addition to the Javadoc syntax, Doxygen supports the documentation tags used in the Qt toolkit and can generate output in HyperText Markup Language (HTML) as well as in Microsoft Compiled HTML Help (CHM), Rich Text Format (RTF), Portable Document Format (PDF), LaTeX, PostScript or man pages.

Uses

Programming languages supported by Doxygen include C,[7] C++, C#, D, Fortran, IDL, Java, Objective-C,[8] Perl,[9] PHP,[10] Python,[11] [12] and VHDL.[10] Other languages can be supported with additional code.

Doxygen runs on most Unix-like systems, macOS, and Windows.

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.

Doxygen has built-in support to generate inheritance diagrams for C++ classes. For more advanced diagrams and graphs, Doxygen can use the "dot" tool from Graphviz.[13]

Example code

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

/**

@param Description of method's or function's input parameter@param ...@return Description of the return value

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

/** * * * * * * @param Description of method's or function's input 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 additional slash as Doxygen comments./// ////// /// ////// @param Description of method's or function's input parameter/// @param .../// @return Description of the return value The following illustrates how a C++ source file can be documented.

/** * @file * @author John Doe * @version 1.0 * * @section LICENSE * * This program is free software; you can redistribute it and/or * modify it under the terms of the GNU General Public License as * published by the Free Software Foundation; either version 2 of * the License, or (at your option) any later version. * * This program is distributed in the hope that it will be useful, but * WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU * General Public License for more details at * https://www.gnu.org/copyleft/gpl.html * * @section DESCRIPTION * * The time class represents a moment of time. */

class Time ;

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

/** * Constructor that sets the time to a given value. */ Time (int timemillis ///< Number of milliseconds passed since Jan 1, 1970.>)

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

/** * * An inline equation @f$ e^+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".[14] 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

Notes and References

  1. http://lists.trolltech.com/qt-interest/1997-10/thread00297-0.html ANNOUNCE: doxygen 0.1
  2. Web site: Doxygen Manual: Frequently Asked Questions. www.doxygen.nl.
  3. Web site: Get With the Program: DIY tips for adding coding to your analysis arsenal . . . 2015-11-22 . Perkel . Jeffrey M. . The Scientist.
  4. Web site: Doxygen . OpenComputing . . 2015-11-22 . Sabin . Mihaela . University of New Hampshire . dead . https://web.archive.org/web/20151123030546/http://foss.unh.edu/resources/index.php/Doxygen . 2015-11-23 .
  5. Web site: Doxygen . Free Software Directory . . 2015-11-22.
  6. Web site: Documentation . . . 2015-11-22.
  7. Web site: Documentation: C . . . 2015-11-22.
  8. Web site: Documentation: Objective-C . . . 2015-11-22.
  9. Web site: Doxygen::Filter::Perl - A perl code pre-filter for Doxygen - metacpan.org. metacpan.org.
  10. Web site: Doxygen Manual: Getting started. www.doxygen.nl.
  11. Web site: Automatic Python API documentation generation tools . python.org wiki . . 2015-11-22.
  12. Web site: doxypypy: A Doxygen filter for Python. Eric W.. Brown. PyPI.
  13. Web site: Doxygen Manual: Graphs and diagrams. www.doxygen.nl.
  14. Web site: doxygen/doxygen. June 9, 2021. GitHub.