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 code 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 code example.
22  *
23  * We often categorize macros in our code. Similarly, when writing doxygen
24  * comments for these categorized macros, we can also group them. See
25  * `DOXYGEN_EXAMPLE_GROUP_A_X`/`DOXYGEN_EXAMPLE_GROUP_A_Y` and
26  * `DOXYGEN_EXAMPLE_GROUP_B_X`/`DOXYGEN_EXAMPLE_GROUP_B_Y` in
27  * <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>
28  * for code example.
29  *
30  * See @ref group_doxygen_example_macro for html output.
31  */
32 
33  /**
34  * @defgroup group_doxygen_example_macro Doxygen Example of Macro
35  *
36  * @ingroup group_doxygen_example
37  *
38  * @brief Doxygen Example of Macro.
39  *
40  * @{
41  */
42 
43 #define DOXYGEN_EXAMPLE_CONST_A 100 /**< Description of macro const A */
44 #define DOXYGEN_EXAMPLE_CONST_B 200 /**< Description of macro const B */
45 
46 /**
47  * @brief Computes the absolute value of its argument @a x.
48  *
49  * @param[in] x input value.
50  *
51  * @return absolute value of @a x.
52  */
53 #define DOXYGEN_EXAMPLE_ABS(x) (((x)>0)?(x):-(x))
54 
55 /**
56  * @defgroup group_doxygen_example_macro_group_a Group A of Macros
57  *
58  * @brief Doxygen Example of Macros grouped in A.
59  *
60  * @{
61  */
62 #define DOXYGEN_EXAMPLE_GROUP_A_X 0x0000 /**< Description of X in group A */
63 #define DOXYGEN_EXAMPLE_GROUP_A_Y 0x0001 /**< Description of Y in group A */
64 /** @} */
65 
66 /**
67  * @defgroup group_doxygen_example_macro_group_b Group B of Macros
68  *
69  * @brief Doxygen Example of Macros grouped in B
70  *
71  * @{
72  */
73 #define DOXYGEN_EXAMPLE_GROUP_B_X 0x0000 /**< Description of X in group B */
74 #define DOXYGEN_EXAMPLE_GROUP_B_Y 0x0001 /**< Description of Y in group B */
75 /** @} */
76 
77 /** @} */
78 
79 #endif
80