Editing Doxygen

{{short description|Documentation generator that supports extracting programming information from many languages}}
{{Infobox software
| name = Doxygen
| title = 
| logo = doxygen.png
| screenshot = Doxygen-1.8.1.png
| caption = 
| collapsible = 
| author = 
| developer = Dimitri van Heesch
| released = {{Start date and age|1997|10|26|df=yes}}<ref>[http://lists.trolltech.com/qt-interest/1997-10/thread00297-0.html ANNOUNCE: doxygen 0.1] {{webarchive
 | url  = https://web.archive.org/web/20111004073015/http://lists.trolltech.com/qt-interest/1997-10/thread00297-0.html
 | date = October 4, 2011}}, ''Announcing: the first release of Doxygen, a C++ documentation system.'' , From: Dimitri van Heesch, Date: Sun, 26 Oct 1997, Qt-interest Archive</ref>
| discontinued = 
| latest release version = {{wikidata|property|preferred|references|edit|P348|P548=Q2804309}}                                             | latest release date    = {{Start date and age|{{wikidata|qualifier|preferred|single|P348|P548=Q2804309|P577}}|df=yes}}
| latest preview version = 
| latest preview date = 
| programming language = [[C++]]
| operating system = [[Cross-platform]]
| platform = 
| size = 
| language = 
| genre = [[Documentation generator]]
| license = [[GNU General Public License|GPLv2]]
| website = {{URL|https://www.doxygen.nl/index.html|doxygen.nl}}
}}

'''Doxygen''' ({{IPAc-en|ˈ|d|ɒ|k|s|i|dʒ|ən}} {{respell|DOK|see-jən}})<ref>{{Cite web|url=https://www.doxygen.nl/manual/faq.html|title=Doxygen Manual: Frequently Asked Questions|website=www.doxygen.nl}}</ref> is a [[documentation generator]]<ref>{{Cite web |url=https://www.the-scientist.com/?articles.view/articleNo/43632/title/Get-With-the-Program/ |title=Get With the Program: DIY tips for adding coding to your analysis arsenal |website=[[The Scientist (magazine)|The Scientist]] |type=[[Trade magazine|Journal]] |date=2015-11-22 |last=Perkel |first=Jeffrey M. |publisher=The Scientist}}</ref><ref>{{Cite web |url=http://foss.unh.edu/resources/index.php/Doxygen |title=Doxygen |website=OpenComputing |type=[[Wiki]] |date=2015-11-22 |last=Sabin |first=Mihaela |publisher=University of New Hampshire |url-status=dead |archiveurl=https://web.archive.org/web/20151123030546/http://foss.unh.edu/resources/index.php/Doxygen |archivedate=2015-11-23 }}</ref><ref>{{Cite web |url=https://directory.fsf.org/wiki/Doxygen |title=Doxygen |website=Free Software Directory |type=[[Wiki]] |date=2015-11-22}}</ref><ref>{{Cite web |url=https://rosettacode.org/wiki/Documentation |title=Documentation |website=[[Rosetta Code]] |type=[[Wiki]] |date=2015-11-22}}</ref> that works with many [[programming language]]s. It extracts information from specially-formatted [[source code]] [[Comment (computer programming)|comments]] and saves the information in one of various supported [[File format|formats]].

Doxygen supports [[Static program analysis|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-reference|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 (programming language)|C]],<ref>{{Cite web |url=https://rosettacode.org/wiki/Documentation#C |title=Documentation: C |website=[[Rosetta Code]] |type=[[Wiki]] |date=2015-11-22}}</ref> [[C++]], [[C Sharp (programming language)|C#]], [[D (programming language)|D]], [[Fortran]], [[Interface Definition Language|IDL]], [[Java (programming language)|Java]], [[Objective-C]],<ref>{{Cite web |url=https://rosettacode.org/wiki/Documentation#Objective-C |title=Documentation: Objective-C |website=[[Rosetta Code]] |type=[[Wiki]] |date=2015-11-22}}</ref> [[Perl]],<ref>{{Cite web|url=https://metacpan.org/pod/Doxygen::Filter::Perl|title=Doxygen::Filter::Perl - A perl code pre-filter for Doxygen - metacpan.org|website=metacpan.org}}</ref> [[PHP]],<ref name="auto">{{Cite web|url=https://www.doxygen.nl/manual/starting.html|title=Doxygen Manual: Getting started|website=www.doxygen.nl}}</ref> [[Python (programming language)|Python]],<ref>{{Cite web |url=https://wiki.python.org/moin/DocumentationTools#Automatic_Python_API_documentation_generation_tools |title=Automatic Python API documentation generation tools |website=python.org wiki |type=[[Wiki]] |date=2015-11-22}}</ref><ref>{{Cite web|url=https://github.com/Feneric/doxypypy|title=doxypypy: A Doxygen filter for Python|first=Eric W.|last=Brown|via=PyPI}}</ref> and [[VHDL]].<ref name="auto"/> It can run on many computers, including [[Unix-like]], [[macOS]], and [[Microsoft Windows|Windows]] systems. It is [[free software]], released under the terms of the [[GNU General Public License|GNU General Public License version{{nbsp}}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.

== Development ==

The Doxygen source code is hosted at [[GitHub]], where the main developer, Dimitri van Heesch, contributes under the name "doxygen".<ref>{{Cite web|url=https://github.com/doxygen/doxygen|title=doxygen/doxygen|date=June 9, 2021|via=GitHub}}</ref> Doxygen is written in C++, and consists of around 300,000 [[source lines of code]]. For [[lexical analysis]], [[Lex (software)|Lex]] (or its replacement Flex) is run via approximately 35,000 lines of lex script. The [[Parsing#Computer_languages|parsing]] tool [[Yacc]] (or its replacement Bison) is also used, but only for minor tasks. The bulk of parsing is done via native C++ code. The [[Software build|build system]] includes [[CMake]] and [[Python (programming language)|Python]] script.

== 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 by immediately preceding it in the code. [[Markup language|Markup]] in the comments allows for controlling inclusion and formatting of the resulting documentation.

Doxygen supports output in many formats including: [[HTML]], [[Microsoft Compiled HTML Help|CHM]], [[Rich Text Format|RTF]], [[Portable Document Format|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]].<ref>{{Cite web|url=https://www.doxygen.nl/manual/diagrams.html|title=Doxygen Manual: Graphs and diagrams|website=www.doxygen.nl}}</ref>

== Example ==

All examples are given for languages with C-like comments where a multi-line comment starts with <code>/*</code> and a single line comment starts with <code>//</code>.

Doxygen ignores a comment unless it is marked specially. For a multi-line comment, the comment must start with <code>/**</code> or <code>/*!</code>. A markup tag is prefixed with a [[backslash]] (<code>\</code>) or an at-sign (<code>@</code>).<ref>[https://www.doxygen.nl/manual/commands.html Doxygen: Special Commands]</ref> The following is a relatively simple function comment block with markup in bold:

 /*'''*'''
 ''Function description''
 '''@param''' ''p1 Parameter description''
 '''@param''' ''p2 Parameter description''
 '''@return''' ''Return description''
 */
 void foo(int p1, int p2) {}

A block can be formatted various ways. A common way is to left-align 
asterisks on each line which Doxygen does not include in the output. For example:

 /*'''*'''
  * ''Function description''
  * '''@param''' ''p1 Parameter description''
  * '''@param''' ''p2 Parameter description''
  * '''@return''' ''Return description''
  */
 void foo(int p1, int p2) {}

Alternatively, a block can consist of a series of single-line comments. Doxygen accepts comments with an additional slash (<code>/</code>) or exclamation (<code>!</code>).<ref>[https://www.doxygen.nl/manual/docblocks.html#cppblock Doxygen: Documenting the code - §Comment blocks for C-like languages]</ref>

 //'''/''' ''Function description''
 //'''/''' '''@param''' ''p1 Parameter description''
 //'''/''' '''@param''' ''p2 Parameter description''
 //'''/''' '''@return''' ''Return description''
 void foo(int p1, int p2) {}

To locate a documentation comment to the right of the code, an additional <code>&lt;</code> marker is required.<ref>[https://www.doxygen.nl/manual/docblocks.html#memberdoc Doxygen: Documenting the code - §Putting documentation after members]</ref> This allows for an alternative approach for documenting parameters as shown below.

 /*'''*'''
  * ''Function description''
  */
 void foo(int p1 /**<Parameter description*/, int p2 /**<Parameter description*/) {}

A mathematic formula can be specified via [[LaTeX]] commands. For example:

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

A more complete example in C++:

<!--
Please regenerate the screenshot image with the latest source code.
[[Image:Doxygen ouput.png|thumb|A screenshot of what the output would look like in HTML]]

There is no guarantee the size of int or long in C/C++ is enough to represent Unix time in milliseconds.
Do not use int or long for time representation. long long or int64_t must be used instead.
-->
<syntaxhighlight lang="cpp">
/**
 * @file
 * @brief Time class header
 * @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>
 */

/**
 * Represents a moment of time
 * @author John Doe
 */
class Time {
public:
    /**
     * Construct with a duration since Jan 1, 1970
     * @param millis A number of milliseconds
     */
    explicit Time(long long millis) : m_millis(millis) {
    }

    /**
     * Get a new instance with the current time
     * @return Instance
     */
    static Time now() {
        // ...
    }

private:
    long long m_millis; ///< Milliseconds since Jan 1, 1970
};
</syntaxhighlight>

== See also ==
{{Portal|Free and open-source software}}

* [[Comparison of documentation generators]]
* [[API Writer]]

== References ==
{{Reflist}}

== External links ==
* {{official website}}

[[Category:Code navigation tools]]
[[Category:Cross-platform software]]
[[Category:Free computer programming tools]]
[[Category:Free documentation generators]]
[[Category:Free software programmed in C++]]
[[Category:Online help]]
[[Category:Software that uses Qt]]