doxygen

Generate a default template configuration file Doxyfile

$ doxygen -g

$ doxygen -g [path/to/config_file]

$ doxygen [path/to/config_file]

doxygen [options] [configuration_file]
doxygen -g [configuration_file]
doxygen -u [configuration_file]
doxygen -x file
doxygen -v

configuration_file
    Specifies the path to the Doxygen configuration file (Doxyfile) to be used. If omitted, doxygen looks for a Doxyfile in the current directory.

-g [configuration_file]
    Generates a new, default configuration file (Doxyfile) at the specified path or in the current directory if no path is given. This is often the first step in setting up doxygen for a project.

-u [configuration_file]
    Updates an existing configuration file. This is useful for adding new configuration options introduced in newer doxygen versions to an older Doxyfile.

-x file
    Extracts documentation from a single source file and prints it to standard output. This mode is useful for quickly previewing how doxygen interprets comments in a specific file.

-q
    Runs doxygen in quiet mode, suppressing most informational messages and warnings. Useful for scripting or automated build processes where only errors are of interest.

-v
    Prints the version information of the doxygen executable and exits.

Doxygen is a comprehensive documentation system widely used in software development to generate API documentation directly from commented source code. It supports numerous programming languages, including C++, C, Java, Objective-C, Python, PHP, C#, Fortran, and others. The primary purpose of doxygen is to keep documentation closely integrated with the code itself, ensuring it stays up-to-date as the codebase evolves.

Developers embed special documentation blocks within their source files, which doxygen then parses. These blocks typically contain descriptions for classes, functions, variables, and parameters, often using specific commands like @param or @return for structured information. Doxygen can output documentation in various popular formats, such as HTML (for browsing), LaTeX (for high-quality printouts, which can then be converted to PDF), man pages, RTF, and XML. Additionally, if the Graphviz tool is installed, doxygen can automatically generate visual diagrams, including inheritance hierarchies, collaboration graphs, and call graphs, which significantly enhance understanding of the code's structure and relationships. This makes doxygen an invaluable tool for maintaining clear, comprehensive, and accessible project documentation.

Doxygen relies heavily on its configuration file, typically named Doxyfile. Misconfigurations can lead to incomplete or incorrect documentation. Achieving optimal output often requires significant tuning of this file.

For generating visual diagrams (e.g., call graphs, inheritance charts), the external Graphviz tool must be installed and accessible in the system's PATH. Without it, doxygen will not be able to produce these graphical outputs.

While highly versatile, doxygen's best results are obtained when source code comments adhere to its specific formatting conventions. Non-standard or poorly structured comments may be ignored or not parsed correctly, leading to missing documentation.

Processing very large codebases can be time-consuming and resource-intensive, potentially impacting build times in continuous integration environments.

The behavior of doxygen is controlled by a configuration file, typically named Doxyfile. This file contains hundreds of configurable options, allowing users to specify input directories, output formats, styling, diagram generation settings, and much more. It is crucial for tailoring doxygen's output to specific project needs. A default Doxyfile can be generated using the doxygen -g command and then edited manually or through a GUI tool like doxywizard (often distributed with doxygen).

Within the special documentation blocks (e.g., /** ... */ in C++), doxygen recognizes various special commands, prefixed with a backslash (\) or an 'at' symbol (@). These commands provide structured information. Examples include \brief or @brief for a short summary, \param or @param for function parameters, \return or @return for return values, and \see or @see for cross-references. Using these commands correctly allows doxygen to parse and present the documentation in a consistent and organized manner across different output formats.

Doxygen was created by Dimitri van Heesch, with its first public release in 1997. Its inception was largely driven by the desire to have a documentation system for C++ that was similar in functionality to Javadoc for Java, but specifically tailored for C++ and capable of understanding its intricate language features. Over time, doxygen expanded its language support significantly, becoming a leading documentation generator not just for C++, but also for C, Objective-C, Python, PHP, and many other languages.

It quickly gained popularity in the open-source community and among developers for its ability to integrate documentation directly into the source code, promoting "self-documenting" code. Its continuous development has added numerous features, including advanced output formats, diagram generation, and extensive configuration options, cementing its position as a robust and widely adopted tool for API documentation.

man(1), groff(1), graphviz(1), javadoc(1), sphinx-build(1)