How to write doxygen documentation for RT-Thread

RT-Thread Online Documentation is created based on doxygen and is available at: https://rt-thread.github.io/rt-thread/. It is consisted of two parts.

One part is the detailed introduction of Kernel, which is written in markdown format and converted into HTML page by doxygen. It is displayed under "RT-Thread User Guide" in Treeview on the left side of the browser. Each sub-chapter is organized into a hierarchical structure by using doxygen's subpage mechanism. To define a page, we use @page command. The page name should be prefixed with a "page_", and the page name should be unique. Besides this, there are no special requirements for writing this part, so I will not go into details in this article.

The other part is the description of API. RT-Thread uses doxygen to automate the generation of documentation from source code comments, parsing information about classes, functions, and variables to produce output in format of HTML. It is displayed under "Modules" in Treeview on the left side of the browser. Each sub-chapter is organized into a hierarchical structure by using doxygen's topics mechanism. The main content of this article is to describe how to write API with doxygen.

General Rules on writing API documentation

Note

The code comments and HTML content generated by doxygen in this guide, for the structures, constants(macro definition), enumeration values, union values, global functions, global variables and other objects involved are all within the scope of the RT-Thread kernel API. The code of internal functions, variables (such as static functions etc.) are not belong to the API scope, how to write comment for these elements are not considered in this guide.

By default, API documentation is written in header files, but there are exceptions, such as for functions.

There are several ways to mark a comment block as a detailed description. We prefer JavaDoc-style (C-style) comment block with some additional markings to document the code, like this:

/**
 * ... text ...
 */

When you want to put documentation after members, we prefer a Qt style, like this:

int var; /**< Detailed description after the member */

When writing comments based on doxygen, several commands defined by doxygen are used. See https://www.doxygen.nl/manual/commands.html for more details about doxygen commands.

More details refer to Doxygen Docs: Documenting the code

Detailed Rules on writing API documentation

This article provide an example.

Click Doxygen Example for the corresponding HTML documentation that is generated by Doxygen.

The contents of Example are described in the following chapters:

• How to use groups in doxygen documentation.
• How to write doxygen documentation for macro.
• How to write doxygen documentation for structure.
• How to write doxygen documentation for union.
• How to write doxygen documentation for enumeration.
• How to write doxygen documentation for typedef.
• How to write doxygen documentation for function.

Build & Run

How to build & run doxygen html on Ubuntu

The following steps are verified on Ubuntu 22.04：

$ lsb_release -a
No LSB modules are available.
Distributor ID: Ubuntu
Description:    Ubuntu 22.04.5 LTS
Release:    22.04
Codename:   jammy

The following packages (and dependents) need to be installed:

$ sudo apt update
$ sudo apt install doxygen
$ sudo apt install graphviz

Assume that the path of RT-Thead code tree is $RTT, execute the following command to build html.

$ cd $RTT/documentation
$ rm -rf html
$ doxygen

A new html directory will be created and all the html files will be placed in this directory.

If you want to quickly browse HTML locally (in Ubuntu environment), you can enter the html directory and start a local HTML server through Python.

$ cd html
$ python3 -m http.server
Serving HTTP on 0.0.0.0 port 8000 (http://0.0.0.0:8000/) ...

A bash script run.sh is provided to automatic upon operations.

$ cd $RTT/documentation
$ ./run.sh

Then open the browser and enter http://<IP>:8000/index.html to access the created html web pages. If it is a local access, then <IP> should be replaced by localhost. If it is a remote access, then <IP> should be replaced by the actual accessible IP address of the machine where HTML is located.

How to build & run doxygen html with Doxywizard

1. download from https://doxygen.nl/index.html
2. open Doxywizard
3. File -> Open
4. Open the file ./Doxyfile
5. To tab Run , Click Run doxygen

How to contribute doxygen comments on vscode more comfortably

There is a script can help you write comments more easily.You can copy the code to your setting.json inner .vscode folder.

"doxdocgen.c.triggerSequence": "/**",
"doxdocgen.c.firstLine": "/**",
"doxdocgen.c.commentPrefix": " * ",
"doxdocgen.c.lastLine": " */",
"doxdocgen.generic.briefTemplate": "@brief ",
 
//You can set param to @param[in] or @param[out] for your preference
"doxdocgen.generic.paramTemplate": "@param[] {param} \n ",
 
//You can comment out returnTemplate to auto addof return value type after @return  
"doxdocgen.generic.returnTemplate": "@return ",
 
//You can comment out customTags to unconfig @note line, meanwhile comment out "empty" item before custom item will make comment more compliant 
"doxdocgen.generic.customTags":[
    "@note "
],
 
"doxdocgen.generic.order":[
    "brief",
    "empty",
    "param",
    "return",
    "empty",
    "custom",
],

If you perfer to write mutiple lines comments at behind one doxygen command, Auto Comment Blocks extension can auto complete "*" at the start of line when you start a new line.