Skip to content

Commit 25ab79e

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 25ab79e

File tree

13 files changed

+557
-57
lines changed

13 files changed

+557
-57
lines changed

‎documentation/0.doxygen/INDEX.md

+114
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,114 @@
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+
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.
12+
13+
@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.
14+
15+
More details refer to [Doxygen Docs: Documenting the code][4]
16+
17+
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:
18+
19+
```
20+
/**
21+
* ... text ...
22+
*/
23+
```
24+
25+
When you want to put documentation after members, we prefer a Qt style, like this:
26+
27+
```
28+
int var; /**< Detailed description after the member */
29+
```
30+
31+
# Detailed Rules on writing API documentation
32+
33+
This article provide an <a href="https://github.com/RT-Thread/rt-thread/blob/master/documentation/0.doxygen/example/">example</a>.
34+
35+
Click @ref group_doxygen_example for the corresponding HTML documentation that is generated by Doxygen.
36+
37+
The contents of Example are described in the following chapters:
38+
39+
- @subpage page_howto_groups
40+
41+
- @subpage page_howto_macro
42+
43+
- @subpage page_howto_struct
44+
45+
- @subpage page_howto_union
46+
47+
- @subpage page_howto_enum
48+
49+
- @subpage page_howto_typedef
50+
51+
- @subpage page_howto_function
52+
53+
# Build & Run
54+
55+
## How to build & run doxygen html on Ubuntu
56+
57+
The following steps are verified on Ubuntu 22.04：
58+
59+
```shell
60+
$ lsb_release -a
61+
No LSB modules are available.
62+
Distributor ID: Ubuntu
63+
Description: Ubuntu 22.04.5 LTS
64+
Release: 22.04
65+
Codename: jammy
66+
```
67+
68+
The following packages (and dependents) need to be installed:
69+
70+
```shell
71+
$ sudo apt update
72+
$ sudo apt install doxygen
73+
$ sudo apt install graphviz
74+
```
75+
76+
Assume that the path of RT-Thead code tree is $RTT, execute the following command to build html.
77+
78+
```shell
79+
$ cd $RTT/documentation
80+
$ rm -rf html
81+
$ doxygen
82+
```
83+
84+
A new html directory will be created and all the html files will be placed in this directory.
85+
86+
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.
87+
88+
```shell
89+
$ cd html
90+
$ python3 -m http.server
91+
Serving HTTP on 0.0.0.0 port 8000 (http://0.0.0.0:8000/) ...
92+
```
93+
94+
A bash script `run.sh` is provided to automatic upon operations.
95+
96+
```shell
97+
$ cd $RTT/documentation
98+
$ ./run.sh
99+
```
100+
101+
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.
102+
103+
## How to build & run doxygen html with Doxywizard
104+
105+
1. download from https://doxygen.nl/index.html
106+
2. open `Doxywizard`
107+
3. `File` -> `Open`
108+
4. Open the file ./Doxyfile
109+
5. To tab `Run` , Click `Run doxygen`
110+
111+
[1]:https://www.doxygen.nl/
112+
[2]:https://www.doxygen.nl/manual/grouping.html#subpaging
113+
[3]:https://www.doxygen.nl/manual/grouping.html#topics
114+
[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)