Doxygen - Quick guide

"Any fool can write code that a computer can understand. Good programmers write code that humans can understand."

— Martin Fowler, Refactoring: Improving the Design of Existing Code, 1999

In Brief

Running the doxygen command in your terminal generates HTML documentation based on the comments in your code.

The steps below outline a quick and basic installation and usage. For more options, refer to the Doxygen documentation.

Installation

On a Mac with Homebrew:

brew install doxygen

Doxygen Configuration

  1. Create a docs directory in your project (or any preferred name).

  2. Open a terminal in this directory and generate a Doxygen configuration file (automatically named Doxyfile) with the command:

    doxygen -g

  3. In the Doxyfile, set at least the following parameters:

    • PROJECT_NAME = "Webserv"
    • INPUT = ../
    • RECURSIVE = YES
    • EXCLUDE = ../folderToExclude1 ../folderToExclude2

Assuming your project's structure is as follows:

├── Makefile
├── README.md
├── docs
│   └── Doxyfile
├── include
│   └── Class.hpp
├── src
│   ├── File.cpp
│   └── main.cpp
├── folderToExclude1
└── folderToExclude2

Create Documentation

Doxygen generates documentation by reading structured comments in the code.

Adding Documentation

Include information in comments using specific keywords. Doxygen reads comments formatted like this (starting with /** and each line with *):

/**
 *
 *
 */

Common keywords include:

Examples

Documenting a File

At the beginning of a file, add:

/**
 * @file Client.cpp
 * @brief Description of the file
 * @version 0.1
 * @date 2024-10-30
 */

Documenting a Function

/**
 * @brief Brief description
 * 
 * @param input Description of the input parameter
 * @param number Description of the number parameter
 * @return int Description of the return value
 */
int Client::functionstring input, int number const {
    int result;
    // function processing
    return result;
}

Generate Documentation

In the docs directory, run:

doxygen

HTML Documentation

This will create an html folder. Open index.html in a browser to view the documentation.

PDF Documentation

Doxygen also creates a latex folder. You can generate a PDF with:

make -C latex pdf

Alternatively, use:

latexmk -pdf refman.tex

refman.tex is the main LaTeX file generated by Doxygen.

Then open refman.pdf

Visual Studio Code Plugin for Doxygen

Install the Doxygen Documentation Generator plugin. It auto-generates Doxygen comment blocks when you type the begin of a comment /**<ENTER>. You can configure fields in the plugin's settings.

LaTeX Installation (on a Mac)

MikTeX is a good option to create LaTeX PDFs because it can automatically install all the packages, so you don't have to do it manually.

  1. Install MikTeX from the official MikTeX site.
  2. Open the app.
  3. Go to Settings > Package Installation > (...) automatically installed > Always.## LaTeX Installation (on a Mac)

References