Doxygen
 | |
| Developer(s) | Dimitri van Heesch |
|---|---|
| Initial release | 26 October 1997[1] |
| Stable release | 1.8.11 / 30 December 2015[2] |
| Written in | C++ |
| Operating system | Cross-platform |
| Type | Documentation generator |
| License | GNU General Public License |
| Website |
doxygen |
Doxygen (/ˈdɒksidʒən/ DOK-see-jən)[3] is a documentation generator,[4][5][6][7] a tool for writing software reference documentation. The documentation is written within code, and is thus relatively easy to keep up to date. 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.
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,[8] C++, C♯, Fortran, IDL, Java, Objective-C,[9] Perl,[10] PHP,[11] Python,[12][13] Tcl, VHDL and others.
It runs on most Unix-like systems, Mac OS X 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.
Example code
The generic syntax of documentation comments is to start a comment with an extra asterisk after the leading comment delimiter '/*':
/**
<A short one line description>
<Longer description>
<May span multiple lines or paragraphs as needed>
@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.
/**
* <A short one line description>
*
* <Longer description>
* <May span multiple lines or paragraphs as needed>
*
* @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.
/// <A short one line description>
///
/// <Longer description>
/// <May span multiple lines or paragraphs as needed>
///
/// @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 <jdoe@example.com>
* @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 {
public:
/**
* Constructor that sets the time to a given value.
*
* @param timemillis Number of milliseconds
* passed since Jan 1, 1970.
*/
Time (int timemillis) {
// the code
}
/**
* Get the current time.
*
* @return A time object set to the current time.
*/
static Time now () {
// the code
}
};
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.>
)
{
// 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]
*
*/
See also
References
- ↑ ANNOUNCE: doxygen 0.1, Announcing: the first release of Doxygen, a C++ documentation system. , From: Dimitri van Heesch, Date: Sun, 26 Oct 1997, Qt-interest Archive
- ↑ van Heesch, Dimitri (2015-12-30). "Release 1.8.11". Doxygen. Retrieved 2015-12-30.
- ↑ FAQ: How did doxygen get its name?
- ↑ Perkel, Jeffrey M. (2015-11-22). "Get With the Program: DIY tips for adding coding to your analysis arsenal". The Scientist (Journal). The Scientist.
- ↑ Sabin, Mihaela (2015-11-22). "Doxygen". OpenComputing (Wiki). University of New Hampshire.
- ↑ "Doxygen". Free Software Directory (Wiki). 2015-11-22.
- ↑ "Documentation". Rosetta Code (Wiki). 2015-11-22.
- ↑ "Documentation: C". Rosetta Code (Wiki). 2015-11-22.
- ↑ "Documentation: Objective-C". Rosetta Code (Wiki). 2015-11-22.
- ↑ http://search.cpan.org/perldoc?Doxygen%3A%3AFilter%3A%3APerl
- ↑ http://www.stack.nl/~dimitri/doxygen/starting.html
- ↑ "Automatic Python API documentation generation tools". python.org wiki (Wiki). 2015-11-22.
- ↑ https://pypi.python.org/pypi/doxypypy/