1@page page_howto_doxygen How to write doxygen documentation for RT-Thread
2
3RT-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.
4
5One 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][2]. 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.
6
7The other part is the description of API. RT-Thread uses [doxygen][1] 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][3]. The main content of this article is to describe how to write API with doxygen.
8
9# General Rules on writing API documentation
10
11@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.
12
13By default, API documentation is written in header files, but there are exceptions, such as for **functions**.
14
15There 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:
16
17```
18/**
19 * ... text ...
20 */
21```
22
23When you want to put documentation after members, we prefer a Qt style, like this:
24
25```
26int var; /**< Detailed description after the member */
27```
28
29When 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.
30
31More details refer to [Doxygen Docs: Documenting the code][4]
32
33# Detailed Rules on writing API documentation
34
35This article provide an <a href="https://github.com/RT-Thread/rt-thread/blob/master/documentation/0.doxygen/example/">example</a>.
36
37Click @ref group_doxygen_example for the corresponding HTML documentation that is generated by Doxygen.
38
39The contents of Example are described in the following chapters:
40
41- @subpage page_howto_groups
42
43- @subpage page_howto_macro
44
45- @subpage page_howto_struct
46
47- @subpage page_howto_union
48
49- @subpage page_howto_enum
50
51- @subpage page_howto_typedef
52
53- @subpage page_howto_function
54
55# Build & Run
56
57## How to build & run doxygen html on Ubuntu
58
59The following steps are verified on Ubuntu 22.04：
60
61```shell
62$ lsb_release -a
63No LSB modules are available.
64Distributor ID:	Ubuntu
65Description:	Ubuntu 22.04.5 LTS
66Release:	22.04
67Codename:	jammy
68```
69
70The following packages (and dependents) need to be installed:
71
72```shell
73$ sudo apt update
74$ sudo apt install doxygen
75$ sudo apt install graphviz
76```
77
78Assume that the path of RT-Thead code tree is $RTT, execute the following command to build html.
79
80```shell
81$ cd $RTT/documentation
82$ rm -rf html
83$ doxygen
84```
85
86A new html directory will be created and all the html files will be placed in this directory.
87
88If you want to quickly browse HTML locally (in Ubuntu environment), you can enter the html directory and start a local HTML server through Python.
89
90```shell
91$ cd html
92$ python3 -m http.server
93Serving HTTP on 0.0.0.0 port 8000 (http://0.0.0.0:8000/) ...
94```
95
96A bash script `run.sh` is provided to automatic upon operations.
97
98```shell
99$ cd $RTT/documentation
100$ ./run.sh
101```
102
103Then 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.
104
105## How to build & run doxygen html with Doxywizard
106
1071. download from https://doxygen.nl/index.html
1082. open `Doxywizard`
1093. `File` -> `Open`
1104. Open the file ./Doxyfile
1115.  To tab `Run` , Click `Run doxygen`
112
113## How to contribute doxygen comments on vscode more comfortably
114
115There is a script can help you write comments more easily.You can copy the code to your setting.json inner .vscode folder.
116
117```json
118"doxdocgen.c.triggerSequence": "/**",
119"doxdocgen.c.firstLine": "/**",
120"doxdocgen.c.commentPrefix": " * ",
121"doxdocgen.c.lastLine": " */",
122"doxdocgen.generic.briefTemplate": "@brief ",
123
124//You can set param to @param[in] or @param[out] for your preference
125"doxdocgen.generic.paramTemplate": "@param[] {param} \n ",
126
127//You can comment out returnTemplate to auto addof return value type after @return
128"doxdocgen.generic.returnTemplate": "@return ",
129
130//You can comment out customTags to unconfig @note line, meanwhile comment out "empty" item before custom item will make comment more compliant
131"doxdocgen.generic.customTags":[
132    "@note "
133],
134
135"doxdocgen.generic.order":[
136    "brief",
137    "empty",
138    "param",
139    "return",
140    "empty",
141    "custom",
142],
143```
144
145If you perfer to write mutiple lines comments at behind one doxygen command, [Auto Comment Blocks][5] extension can auto complete "*" at the start of line when you start a new line.
146
147[1]:https://www.doxygen.nl/
148[2]:https://www.doxygen.nl/manual/grouping.html#subpaging
149[3]:https://www.doxygen.nl/manual/grouping.html#topics
150[4]:https://www.doxygen.nl/manual/docblocks.html
151[5]:https://marketplace.visualstudio.com/items?itemName=kevinkyang.auto-comment-blocks
152