A Brief Overview of Doxygen¶

Doxygen is a tool for generating code documentation for various programming languages. It has become the standard for C/C++ documentation and is a free and open source tool. It exists for major computer operating systems including Windows, Mac and Linux.

Quickstart¶

Installation

Have a look at the official website of Doxygen and download the appropriate file for your system here. For Debian-based GNU/Linux systems like Ubuntu, you can also install it using APT package manager. Use followed command:

apt update
apt install doxygen

Configuration

Doxygen uses a configuration file to set various properties. This file is called Doxyfile. To create this file with default properties, doxygen offers the following command:

doxygen -g

In order to get an html output as quickly as possible, set the following variables in the project configuration file:

• PROJECT_NAME:

  Set the name of the project.

  # The PROJECT_NAME tag is a single word (or a sequence of words surrounded by
  # double-quotes, unless you are using Doxywizard) that should identify the
  # project for which the documentation is generated. This name is used in the
  # title of most generated pages and in a few other places.
  # The default value is: My Project.
  
  PROJECT_NAME           = "My Project"
  

• OPTIMIZE_OUTPUT_FOR_C

  Optimize doxygen output for C code.

  # Set the OPTIMIZE_OUTPUT_FOR_C tag to YES if your project consists of C sources
  # only. Doxygen will then generate output that is more tailored for C. For
  # instance, some of the names that are used will be different. The list of all
  # members will be omitted, etc.
  # The default value is: NO.
  
  OPTIMIZE_OUTPUT_FOR_C = YES
  

• INPUT

  Specify the paths to all directories and files that Doxygen’s documentation processor should include. These are directories and files that contain documentation. If you want to add subdirectories, use the configuration parameter below to add them.

  # The INPUT tag is used to specify the files and/or directories that contain
  # documented source files. You may enter file names like myfile.cpp or
  # directories like /usr/src/myproject. Separate the files or directories with
  # spaces. See also FILE_PATTERNS and EXTENSION_MAPPING
  # Note: If this tag is empty the current directory is searched.
  
  INPUT =
  

• RECURSIVE

  Enable or disable subdirectories search.

  # The RECURSIVE tag can be used to specify whether or not subdirectories should
  # be searched for input files as well.
  # The default value is: NO.
  
  RECURSIVE = NO
  

• USE_MDFILE_AS_MAINPAGE

  Add the README file to the index page of the documentation. Alternatively, you can write a separate Markdown file.

  # If the USE_MDFILE_AS_MAINPAGE tag refers to the name of a markdown file that
  # is part of the input, its contents will be placed on the main page
  # (index.html). This can be useful if you have a project on for instance GitHub
  # and want to reuse the introduction page also for the doxygen output.
  
  USE_MDFILE_AS_MAINPAGE =
  

• BUILD ONLY HTML OUTPUT:

  # If the GENERATE_HTML tag is set to YES, doxygen will generate HTML output
  # The default value is: YES.
  
  GENERATE_HTML = YES
  # If the GENERATE_LATEX tag is set to YES, doxygen will generate LaTeX output.
  # The default value is: YES.
  
  GENERATE_LATEX = NO
  

After configuration, run the doxygen generator with:

doxygen

In the newly created directory, called html, your documentation website is created. The site can be viewed in your favourite web browser by opening the index.html file, for example:

firefox html/index.html

Doxygen Comments¶

Special comment blocks

Doxygen comments are extended comments in the language being used. Initially only used for C/C++ projects, Doxygen now supports several programming languages. Look at the official documentation in Documenting the code for your language to see how the special comment blocks for Doxygen are marked.

The special comment blocks are decorated with special commands/tags. These tags control the output of the documentation for the part of the code that is being documented.

File header

Doxygen file headers are used to give a brief overview of the function of the file. It also includes the author, version, date, copyright and filename. Of course the description can be extended with more special commands like todo or bug.

/**
 * @file codeSnippet.c
 * @author John DOE (john.doe@bfh.ch)
 * @brief This is a short descrition 
 *  about the functionality 
 *  in this source file
 * @version 0.1
 * @date 2023-11-21
 * 
 * @copyright Copyright (c) 2023
 * 
 */

Code description

A big advantage of Doxygen is the documentation of functions as well as structs, typedefs and variables. This results in extensive documentation that is useful for other developers and for you.

/**
 * @brief Calculates the difference between minuend and subtrahend
 * 
 * @param minuend the minuend of the subtraction 
 * @param subtrahend the subtrahend of the subtraction
 * @return int the difference 
 */
int diff(int minuend, int subtrahend);

/**
 * @brief Structure to save the current time
 * 
 */
struct myTime
{
    uint8_t hour; ///< The current hour 
    uint8_t minute; ///< The current minute
    uint8_t second; ///< The current second
};

#define MAX_VALUE_SECOND 59 ///< Maximum value of a second

ext install cschlosser.doxdocgen