Doxygen ( ) is a documentation generator 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 A parse tree or parsing tree or derivation tree or concrete syntax tree is an ordered, rooted tree that represents the syntactic structure of a string according to some context-free grammar. The term ''parse tree'' itself is used primarily in co ...

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 Free software or libre software is computer software distributed under terms that allow users to run the software for any purpose as well as to study, change, and distribute it and any adapted versions. Free software is a matter of liberty, n ...

, 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 Qt (pronounced "cute") is cross-platform software for creating graphical user interfaces as well as cross-platform applications that run on various software and hardware platforms such as Linux, Windows, macOS, Android or embedded systems wi ...

and can generate output in HyperText Markup Language (

HTML The HyperText Markup Language or HTML is the standard markup language for documents designed to be displayed in a web browser. It can be assisted by technologies such as Cascading Style Sheets (CSS) and scripting languages such as JavaS ...

) as well as in Microsoft Compiled HTML Help (CHM),

Rich Text Format ) As an example, the following RTF code would be rendered as follows: This is some bold text. Character encoding A standard RTF file can only consist of 7-bit ASCII characters, but can use escape sequences to encode other characters. T ...

(RTF),

Portable Document Format Portable Document Format (PDF), standardized as ISO 32000, is a file format developed by Adobe in 1992 to present documents, including text formatting and images, in a manner independent of application software, hardware, and operating syste ...

(PDF),

LaTeX Latex is an emulsion (stable dispersion) of polymer microparticles in water. Latexes are found in nature, but synthetic latexes are common as well. In nature, latex is found as a milky fluid found in 10% of all flowering plants (angiosperms ...

PostScript PostScript (PS) is a page description language in the electronic publishing and desktop publishing realm. It is a dynamically typed, concatenative programming language. It was created at Adobe Systems by John Warnock, Charles Geschke, Do ...

or man pages.

Uses

Programming language A programming language is a system of notation for writing computer programs. Most programming languages are text-based formal languages, but they may also be graphical. They are a kind of computer language. The description of a programming ...

s supported by Doxygen include C, C++, C#, D, Fortran, IDL,

Java Java (; id, Jawa, ; jv, ꦗꦮ; su, ) is one of the Greater Sunda Islands in Indonesia. It is bordered by the Indian Ocean to the south and the Java Sea to the north. With a population of 151.6 million people, Java is the world's mo ...

Objective-C Objective-C is a general-purpose, object-oriented programming language that adds Smalltalk-style messaging to the C programming language. Originally developed by Brad Cox and Tom Love in the early 1980s, it was selected by NeXT for its NeXT ...

Perl Perl is a family of two high-level, general-purpose, interpreted, dynamic programming languages. "Perl" refers to Perl 5, but from 2000 to 2019 it also referred to its redesigned "sister language", Perl 6, before the latter's name was offic ...

, PHP, Python, and VHDL. Other languages can be supported with additional code. Doxygen runs on most

Unix-like A Unix-like (sometimes referred to as UN*X or *nix) operating system is one that behaves in a manner similar to a Unix system, although not necessarily conforming to or being certified to any version of the Single UNIX Specification. A Unix-li ...

systems,

macOS macOS (; previously OS X and originally Mac OS X) is a Unix operating system developed and marketed by Apple Inc. since 2001. It is the primary operating system for Apple's Mac computers. Within the market of desktop and la ...

, and

Windows Windows is a group of several proprietary graphical operating system families developed and marketed by Microsoft. Each family caters to a certain sector of the computing industry. For example, Windows NT for consumers, Windows Server for se ...

. 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 The Zuse Institute Berlin (abbreviated ZIB, or ''Konrad-Zuse-Zentrum für Informationstechnik Berlin'') is a research institute for applied mathematics and computer science on the campus of Freie Universität Berlin in Dahlem, Berlin, Germa ...

. 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.

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

commands: /** * * An inline equation @f$ e^+1 = 0 @f$ * * A displayed equation: @f e^+1 = 0 @f * */

Doxygen source and development

The Doxygen sources are currently hosted at

GitHub GitHub, Inc. () is an Internet hosting service for software development and version control using Git. It provides the distributed version control of Git plus access control, bug tracking, software feature requests, task management, cont ...

, 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 Parsing, syntax analysis, or syntactic analysis is the process of analyzing a string of symbols, either in natural language, computer languages or data structures, conforming to the rules of a formal grammar. The term ''parsing'' comes from ...

tool

Yacc Yacc (Yet Another Compiler-Compiler) is a computer program for the Unix operating system developed by Stephen C. Johnson. It is a Look Ahead Left-to-Right Rightmost Derivation (LALR) parser generator, generating a LALR parser (the part of a co ...

(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 In software development, CMake is cross-platform free and open-source software for build automation, testing, packaging and installation of software by using a compiler-independent method. CMake is not a build system itself; it generates a ...

and also involves some Python scripts.

References

External links