doxygen Command in Linux

---

---

The Linux doxygen command is a documentation system that generates documentation for various programming languages. It is an open-source command line utility that documents a program through specified comments. It offers three output formats HTML, LaTeX, or RTF.

The program documentation process starts with the developer’s comments. If the comments are properly added to the program, then the doxygen utility can quickly create the documentation.

The doxygen can document programs in many programming languages such as C, C++, C#, Objective C, Java, Python, PHP, and more.

Table of Contents

Here is a comprehensive guide to the options available with the doxygen command −

• Prerequisites to Use the doxygen Command
• Syntax of doxygen Command
• doxygen Command Options
• Doxygen-Supported Comment Blocks
• Doxygen Keywords
• Getting Started with Doxygen
• Examples of doxygen Command in Linux

Prerequisites to Use the doxygen Command

To create documentation using doxygen, it needs to be installed. The commands to install it in Linux are given below −

Ubuntu, Debian, and Debian-based distributions −

sudo apt install doxygen 

CentOS, RHEL, Fedora, and distributions based on these Linux distributions −

sudo yum install doxygen

To verify the installation of doxygen, check its version −

Syntax of doxygen Command

The syntax of using the Linux doxygen command is as follows −

doxygen [options] [filename]

The [options] in the syntax is used to specify options to create configuration files and get output in various formats. The [filename] option is used to specify the configuration file name.

doxygen Command Options

The commonly used options for the Linux doxygen command are listed below −

Doxygen-Supported Comment Blocks

The doxygen command supports various commenting styles to add documentation details to the program. They are listed below −

1. Javadoc style −

/**
* …Comments…
*/

2. Qt style −

/*!
* …Comments…
*/

The intermediate asterisks are optional in the above cases. For instance −

/**
…Comments…
*/

3. C++ style −

///
/// …Comments…
///

Or −

//!
//! …Comments…
//!

The first and last lines must be black (///, //!).

4. Other styles −

/////////////////////////////
/// …Comments…
/////////////////////////////

Or −

/****************************
*…Comments…
****************************/

Doxygen Keywords

The doxygen keywords can be mentioned to specify various fields in the code. They are listed below −

Getting Started with Doxygen

Creating documentation using the doxygen command requires two files, a marked program file, and a configuration file. Follow through the following sections to learn how to create these files.

Note: The program file path can be mentioned in the configuration file. In this example, the program file and configuration file are created in the same directory for ease.

Marking a Program File

Before creating the documentation using doxygen, a program must be commented on using the special doxygen keywords.

The following C++ example code contains a calculator class, and two methods (add, subtract). The class, methods, and parameters are marked using the doxygen keywords −

#include <iostream>

using namespace std;

/**
 * @class Calculator
 * @brief A calculator class to perform addition and subtraction.
 */

class Calculator {
   public:
      /**
      * @brief Default constructor.
      */
      Calculator();

      /**
      * @brief Adds two integers.
      * @param a The first integer.
      * @param b The second integer.
      * @return The sum of a and b.
      */
      int add(int a, int b);

      /**
      * @brief Subtracts one integer from another.
      * @param a The integer to subtract from.
      * @param b The integer to subtract.
      * @return The difference between a and b.
      */
      int subtract(int a, int b);
};

/**
 * @brief Default constructor implementation.
 */
Calculator::Calculator() {
   // Constructor code can be added here if needed.
   cout << "Calculator object created!" << endl;
}

/**
 * @brief Adds two integers.
 * @param a The first integer.
 * @param b The second integer.
 * @return The sum of a and b.
 */
int Calculator::add(int a, int b) {
   return a + b;
}

/**
 * @brief Subtracts one integer from another.
 * @param a The integer to subtract from.
 * @param b The integer to subtract.
 * @return The difference between a and b.
 */
int Calculator::subtract(int a, int b) {
   return a - b;
}

/**
 * @brief The main function that demonstrates the use of Calculator class.
 * @return 0 if the program completes successfully.
 */
int main() {
   Calculator calc;
   int a = 10, b = 5;

   cout << "Sum of " << a << " and " << b << " is: " << calc.add(a, b) << endl;
   cout << "Difference of " << b << " from " << a << " is: " << calc.subtract(a, b) << endl;

   return 0;
}

The example code provides a brief overview of how doxygen keywords are used.

Creating a Configuration File

The configuration file is used to set the options for the documentation such as program directory, output directory, document name, and other options. To create a doxygen configuration file, use the -g option.

doxygen -g [filename]

The configuration file can be created using any name. For instance, to create a configuration file in the current working directory with the name of doxy.conf, execute −

doxygen -g doxy.conf

To generate the configuration file without the comments, use -s −

doxygen -s -g doxy.conf

The configuration file can be modified to customize the documentation according to the mentioned options. Important fields to be set are −

If the program file is in the same directory then use dot against INPUT field.

Note: To prevent errors, ensure that INPUT and OUTPUT_DIRECTORY are correctly specified.

After generating and modifying the configuration file, the next step is to create the documentation.

Examples of doxygen Command in Linux

This section demonstrates how to create a program documentation using the doxygen command −

• Generating Documentation
• Generating Template Style Sheets

Generating Documentation

To generate documentation, run the doxygen command with the configuration file's name in the directory where the file is located.

doxygen doxy.conf

An html directory will be generated in the current directory, open it. Identify the index.html file and open it. The generated documentation will be opened in the browser.

The class and methods briefs can easily be navigated −

Through this simple process, the documentation of any program can easily be created.

Generating Template Style Sheets

To generate documentation configuration files such as header, footer, and stylesheets of a specific format, the -w option is used. These files help in further customizing the output.

For instance, to generate a configuration file with a header, footer, and stylesheets files, use the following command −

doxygen -w html headerfile.html footerfile.html stylesheet.css

After generating these files, modify the configuration file fields mentioned below −

HTML_HEADER= headerfile.html
HTML_FOOTER= footerfile.html
HTML_EXTRA_STYLESHEET= stylesheet.css

For LaTeX −

doxygen -w latex headerfile.tex stylesheet.sty

For RTF −

doxygen -w rtf stylesheet.sty

Like HTML, both the LaTeX and RTF files must also be configured in the configuration file.

Conclusion

The doxygen command on Linux is used to create documentation of a program commented using doxygen keywords. It can generate documentation in HTML, LaTeX, and RTF formats. It is a powerful tool that allows full customization of the output file.

To create documentation, mark the code first, create a configuration file, and configure it according to the need. After that execute the doxygen command and generate documentation.

In this tutorial, we covered the doxygen command, its installation, syntax, options, and usage.