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