Skip to content

Commit 2b6abda

Browse files
unicornxunicornx
committed
doxygen: add documentation for doxygen
Documentation is provided to clarify how to write doxygen documentation for RT-Thread. This document is also integrated as part of RT-Thread doxygen documentation. An example is also provided. The original README.md is removed and integrated into this document. Signed-off-by: Chen Wang <[email protected]>
1 parent 8629c95 commit 2b6abda

File tree

13 files changed

+559
-57
lines changed

13 files changed

+559
-57
lines changed

‎documentation/0.doxygen/INDEX.md

+116
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,116 @@
1+
@page howto_doxygen How to write doxygen documentation for RT-Thread
2+
3+
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.
4+
5+
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][2]. There are no special requirements for writing this part, so I will not go into details in this article.
6+
7+
The 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+
13+
By default, API documentation is written in header files, but there are exceptions, such as for **functions**.
14+
15+
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:
16+
17+
```
18+
/**
19+
* ... text ...
20+
*/
21+
```
22+
23+
When you want to put documentation after members, we prefer a Qt style, like this:
24+
25+
```
26+
int var; /**< Detailed description after the member */
27+
```
28+
29+
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.
30+
31+
More details refer to [Doxygen Docs: Documenting the code][4]
32+
33+
# Detailed Rules on writing API documentation
34+
35+
This article provide an <a href="https://github.com/RT-Thread/rt-thread/blob/master/documentation/0.doxygen/example/">example</a>.
36+
37+
Click @ref group_doxygen_example for the corresponding HTML documentation that is generated by Doxygen.
38+
39+
The 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+
59+
The following steps are verified on Ubuntu 22.04：
60+
61+
```shell
62+
$ lsb_release -a
63+
No LSB modules are available.
64+
Distributor ID: Ubuntu
65+
Description: Ubuntu 22.04.5 LTS
66+
Release: 22.04
67+
Codename: jammy
68+
```
69+
70+
The 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+
78+
Assume 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+
86+
A new html directory will be created and all the html files will be placed in this directory.
87+
88+
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.
89+
90+
```shell
91+
$ cd html
92+
$ python3 -m http.server
93+
Serving HTTP on 0.0.0.0 port 8000 (http://0.0.0.0:8000/) ...
94+
```
95+
96+
A bash script `run.sh` is provided to automatic upon operations.
97+
98+
```shell
99+
$ cd $RTT/documentation
100+
$ ./run.sh
101+
```
102+
103+
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.
104+
105+
## How to build & run doxygen html with Doxywizard
106+
107+
1. download from https://doxygen.nl/index.html
108+
2. open `Doxywizard`
109+
3. `File` -> `Open`
110+
4. Open the file ./Doxyfile
111+
5. To tab `Run` , Click `Run doxygen`
112+
113+
[1]:https://www.doxygen.nl/
114+
[2]:https://www.doxygen.nl/manual/grouping.html#subpaging
115+
[3]:https://www.doxygen.nl/manual/grouping.html#topics
116+
[4]:https://www.doxygen.nl/manual/docblocks.html

‎documentation/0.doxygen/doxygen.h

+9
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
/*
2+
* This file is only used for doxygen document generation.
3+
*/
4+
5+
/**
6+
* @defgroup group_doxygen_example Doxygen Example
7+
*
8+
* @brief Introduce how to write doxygen documentation.
9+
*/

‎documentation/0.doxygen/example/include/enum.h

+37
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
#ifndef _DOXYGEN_EXAMPLE_ENUM_H_
2+
#define _DOXYGEN_EXAMPLE_ENUM_H_
3+
4+
/**
5+
* @page page_howto_enum How to write doxygen documentation for enumeration.
6+
*
7+
* A comment block before the enumeration definition is recommended to
8+
* describe the general information of the enumeration type. In the
9+
* comment block, a `@brief` is required, other commands (such as `@note`)
10+
* are optional.
11+
*
12+
* To describe the values of the enumeration, document is recommended
13+
* to be put after each value.
14+
*
15+
* See
16+
* <a href="https://github.com/RT-Thread/rt-thread/blob/master/documentation/0.doxygen/example/include/enum.h">documentation/0.doxygen/example/include/enum.h</a>
17+
* for example.
18+
*/
19+
20+
/**
21+
* @addtogroup group_doxygen_example
22+
*/
23+
24+
/** @{ */
25+
26+
/**
27+
* @brief Brief description of this enumeration
28+
*/
29+
enum doxygen_example_enum
30+
{
31+
V1, /**< description for value 1 */
32+
V2, /**< description for value 2 */
33+
};
34+
35+
/** @} */
36+
37+
#endif /* _DOXYGEN_EXAMPLE_ENUM_H_ */

‎documentation/0.doxygen/example/include/function.h

+7
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
#ifndef _DOXYGEN_EXAMPLE_FUNCTION_H_
2+
#define _DOXYGEN_EXAMPLE_FUNCTION_H_
3+
4+
void doxygen_example_func_foo(int a, int b);
5+
int doxygen_example_func_bar(int a, int* b);
6+
7+
#endif /* _DOXYGEN_EXAMPLE_FUNCTION_H_ */

‎documentation/0.doxygen/example/include/groups.h

+74
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,74 @@
1+
#ifndef _DOXYGEN_EXAMPLE_GROUPS_H_
2+
#define _DOXYGEN_EXAMPLE_GROUPS_H_
3+
4+
/**
5+
* @page page_howto_groups How to use groups in doxygen documentation.
6+
*
7+
* Doxygen has three mechanisms to group things together. For RT-Thread
8+
* API documentation, we use 'topics' to create new page for each group.
9+
* On HTML browser, the topics pages are shown under the "Modules" in the
10+
* treeview on the left.
11+
*
12+
* To define a group, we use `@defgroup` command. The group name should be
13+
* prefixed with a "group_", and the group name should be unique. We can
14+
* define a group anywhere, not necessarily in the same file as the members
15+
* of the group. Generally, we define a group in a header file.
16+
*
17+
* To make an entity (structure, function etc. or another group) a menber of
18+
* a speicific group, we can use `@ingroup` command and put the `@ingroup`
19+
* command inside its documentation block.
20+
*
21+
* To avoid putting `@ingroup` commands in the documentation for each member
22+
* you can use `@addtogroup` and group members together by the open marker
23+
* `@{` before the group and the closing marker `@}` after the group.
24+
*
25+
* See
26+
* <a href="https://github.com/RT-Thread/rt-thread/blob/master/documentation/0.doxygen/example/include/groups.h">documentation/0.doxygen/example/include/groups.h</a>
27+
* for example.
28+
*
29+
* More information can be found in the Doxygen manual:
30+
* <a href="https://www.doxygen.nl/manual/grouping.html">Grouping</a>.
31+
*/
32+
33+
/**
34+
* @defgroup group_doxygen_example_sub Sub Group of Doxygen Example
35+
*
36+
* All members of this group will be displayed in one HTML page.
37+
*
38+
* @ingroup group_doxygen_example
39+
*
40+
* @brief Define a sub group of Doxygen Example.
41+
*/
42+
43+
/**
44+
* @brief Brief description of this enumeration
45+
*
46+
* We use `@ingroup` to add this enum to the group_doxygen_example_sub separately.
47+
*
48+
* @ingroup group_doxygen_example_sub
49+
*/
50+
enum doxygen_example_enum_2
51+
{
52+
V1, /**< description for value 1 */
53+
V2, /**< description for value 2 */
54+
};
55+
56+
// This entity is not a member of any group.
57+
#define DOXYGEN_EXAMPLE_CONST_E 300 /**< Description of macro const D */
58+
59+
/**
60+
* @addtogroup group_doxygen_example_sub
61+
*/
62+
63+
/** @{ */
64+
65+
/*
66+
* DOXYGEN_EXAMPLE_CONST_C & DOXYGEN_EXAMPLE_CONST_D are close together, so
67+
* we can use `@addtogroup`, `@{` and `@}` to group them together.
68+
*/
69+
#define DOXYGEN_EXAMPLE_CONST_C 100 /**< Description of macro const C */
70+
#define DOXYGEN_EXAMPLE_CONST_D 200 /**< Description of macro const D */
71+
72+
/** @} */
73+
74+
#endif /* _DOXYGEN_EXAMPLE_GROUPS_H_ */

‎documentation/0.doxygen/example/include/macro.h

+44
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,44 @@
1+
#ifndef _DOXYGEN_EXAMPLE_MACRO_H_
2+
#define _DOXYGEN_EXAMPLE_MACRO_H_
3+
4+
/**
5+
* @page page_howto_macro How to write doxygen documentation for macro.
6+
*
7+
* There are two typical types of macro definitions.
8+
*
9+
* - One is to define constant macros. For this type of macro, we
10+
* recommend putting documentation after members. See `DOXYGEN_EXAMPLE_CONST_A`
11+
* and `DOXYGEN_EXAMPLE_CONST_B` in
12+
* <a href="https://github.com/RT-Thread/rt-thread/blob/master/documentation/0.doxygen/example/include/macro.h">documentation/0.doxygen/example/include/macro.h</a>
13+
* for exmaple.
14+
*
15+
* - The other is to define macros with parameters. For this type of
16+
* macro, we recommend using a method similar to documenting for
17+
* functions, that is, writing comment block before the macro definition.
18+
* More details please see @ref page_howto_function
19+
* See `DOXYGEN_EXAMPLE_ABS` in
20+
* <a href="https://github.com/RT-Thread/rt-thread/blob/master/documentation/0.doxygen/example/include/macro.h">documentation/0.doxygen/example/include/macro.h</a>
21+
* for example.
22+
*/
23+
24+
/**
25+
* @addtogroup group_doxygen_example
26+
*/
27+
28+
/** @{ */
29+
30+
#define DOXYGEN_EXAMPLE_CONST_A 100 /**< Description of macro const A */
31+
#define DOXYGEN_EXAMPLE_CONST_B 200 /**< Description of macro const B */
32+
33+
/**
34+
* @brief Computes the absolute value of its argument @a x.
35+
*
36+
* @param[in] x input value.
37+
*
38+
* @return absolute value of @a x.
39+
*/
40+
#define DOXYGEN_EXAMPLE_ABS(x) (((x)>0)?(x):-(x))
41+
42+
/** @} */
43+
44+
#endif

‎documentation/0.doxygen/example/include/struct.h

+78
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,78 @@
1+
#ifndef _DOXYGEN_EXAMPLE_STRUCT_H_
2+
#define _DOXYGEN_EXAMPLE_STRUCT_H_
3+
4+
/**
5+
* @page page_howto_struct How to write doxygen documentation for structure.
6+
*
7+
* We recommend the following approach:
8+
*
9+
* A comment block before the structure definition is recommended to
10+
* describe the general information of the structure type. In the
11+
* comment block, a `@brief` is required, other commands (such as `@note`)
12+
* are optional.
13+
*
14+
* If you feel that the description of `@brief` is not enough, you
15+
* can add a detailed description part, which is also optional.
16+
*
17+
* Put member comments inside the structure definition and after every member.
18+
*
19+
* See
20+
* <a href="https://github.com/RT-Thread/rt-thread/blob/master/documentation/0.doxygen/example/include/struct.h">documentation/0.doxygen/example/include/struct.h</a>
21+
* for example.
22+
*/
23+
24+
/**
25+
* @addtogroup group_doxygen_example
26+
*/
27+
28+
/** @{ */
29+
30+
/**
31+
* @brief Brief description this structure
32+
*
33+
* Detailed description starts here, one line or multiple lines.
34+
* Blah blah blah...
35+
*
36+
* @note This is a note for this structure, blah blah blah...
37+
*/
38+
struct dogygen_example_struct
39+
{
40+
int m1; /**< Some documentation for member 'm1'...
41+
* Multiple lines ... Note the "multi-line" here refers
42+
* to the code. Whether it is displayed in multiple lines
43+
* on the specific HTML page depends on the browser rendering.
44+
*
45+
* @note We can also embed note for member 'm1'...
46+
*/
47+
int m2; /**< Some documentation for member 'm2'... */
48+
int m3; /**< Some documentation for member 'm3'... */
49+
int m4; /**< Some documentation for member 'm4'... */
50+
int m5; /**< Some documentation for member 'm5'... */
51+
};
52+
53+
/**
54+
* @brief Brief description this structure
55+
*
56+
* Detailed description starts here, one line or multiple lines.
57+
* Blah blah blah...
58+
*
59+
* @note This is a note for this structure, blah blah blah...
60+
*/
61+
struct dogygen_example_struct_another
62+
{
63+
int m1; /**< Some documentation for member 'm1'...
64+
* Multiple lines ... Note the "multi-line" here refers
65+
* to the code. Whether it is displayed in multiple lines
66+
* on the specific HTML page depends on the browser rendering.
67+
*
68+
* @note We can also embed note for member 'm1'...
69+
*/
70+
int m2; /**< Some documentation for member 'm2'... */
71+
int m3; /**< Some documentation for member 'm3'... */
72+
int m4; /**< Some documentation for member 'm4'... */
73+
int m5; /**< Some documentation for member 'm5'... */
74+
};
75+
76+
/** @} */
77+
78+
#endif /* _DOXYGEN_EXAMPLE_STRUCT_H_ */

0 commit comments

Comments
 (0)