1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
|
/**
* @page page_howto_function How to write doxygen documentation for function.
*
* Function comments can be placed in the header file (before the
* function declaration) OR in the source file (before the function
* definition).
*
* The advantage of placing it in the header file is that we generally
* think that the header file is the place to declare the API, but the
* problem is that when a module has many API extern functions, if the
* comments are placed in the header file, the header file will be very
* long. You can imagine that for a module with many APIs and many
* comments, the header file will be full of large green comments, and
* the function declaration part is mixed in the middle and difficult
* to distinguish. And if you want to fully understand which extern
* functions this module exports, you need to scroll a long file for a
* long time to get a general idea. Especially for RTT, see `include/rtthread.h`
* as an example.
*
* Putting the comment in the source file can avoid the above problems.
* For developers, it is also convenient to read the comments together with
* the code implementation. The disadvantage is that it would be different
* from the function side, from other types, such as structures, i.e. the API
* comments of functions need to be read in the source file instead of directly
* in the header file.
*
* Comprehensive consideration can be combined with the actual situation.
* For example, if there are too many API functions in a header file, it is
* recommended to put the function comments in the source file.
*
* So, it is **strongly recommended** to put comments in the source file when
* writing new functions or annotating functions.
*
* To documenting for functions, a comment block before the function
* declaraion/definition is recommended to describe the general information
* of the function. In the comment block, a `@brief` is required. A `@return`
* is also required if the function is intended to return a value, otherwise
* if the function is implemented with a void return type, `@return` is not
* required. `@param` is required if any, and if it is provided,
* direction [in]/[out]/[in,out] should be provide together. Other commands
* (such as `@note`) are optional.
*
* If you feel that the description of `@brief` is not enough, you
* can add a detailed description part, which is also optional.
*
* See
* <a href="https://github.com/RT-Thread/rt-thread/blob/master/documentation/0.doxygen/example/src/function.c">documentation/0.doxygen/example/src/function.c</a>
* for code example.
*
* See @ref group_doxygen_example_function for html output.
*
* @note <a href="https://github.com/RT-Thread/rt-thread/blob/master/documentation/0.doxygen/example/src/function.h">documentation/0.doxygen/example/src/function.h</a>
* is just an example of the header file where we declare the API without
* doxygen documentation.
*/
/**
* @defgroup group_doxygen_example_function Doxygen Example of Function
*
* @ingroup group_doxygen_example
*
* @brief Doxygen Example of Function.
*
* @{
*/
/**
* @brief Brief description for the function
*
* Detailed description starts here, one line or multiple lines.
* Blah blah blah...
*
* @param[in] a Description of param a
*
* @param[in] b Description of param b
*
* @note This is a note for this structure, blah blah blah...
*/
void doxygen_example_func_foo(int a, int b)
{
return;
}
/**
* @brief Brief description for the function
*
* Detailed description starts here, one line or multiple lines.
* Blah blah blah...
*
* @param[in] a Description of param a
*
* @param[out] b Description of param b
*
* @return the return value, 0 for success, -1 for failure
*
* @note This is a note for this structure, blah blah blah...
*/
int doxygen_example_func_bar(int a, int* b)
{
return 0;
}
/** @} */
|
