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 * See `struct dogygen_example_struct` for example. 19 * 20 * If the structure member is too long (this often happens when the structure 21 * member is a callback function), when the comment is written after the member, 22 * it will make the code line too long. In this case, we can also put the comment 23 * before the member. See `struct dogygen_example_struct_another` for example. 24 * 25 * Going a step further, for this kind of structure whose members are callback 26 * functions, we can describe the members in style for functions, it is more 27 * complicated and contains more content. It is useful when we want to describe 28 * the parameters and return values of the callback function in more detail. 29 * See `struct dogygen_example_struct_another2` for example. 30 * 31 * See 32 * <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> 33 * for code example. 34 * 35 * See @ref group_doxygen_example_struct for html output. 36 */ 37 38 /** 39 * @defgroup group_doxygen_example_struct Doxygen Example of Structure 40 * 41 * @ingroup group_doxygen_example 42 * 43 * @brief Doxygen Example of Structure. 44 * 45 * @{ 46 */ 47 48 /** 49 * @brief Brief description this structure 50 * 51 * Detailed description starts here, one line or multiple lines. 52 * Blah blah blah... 53 * 54 * @note This is a note for this structure, blah blah blah... 55 */ 56 struct dogygen_example_struct 57 { 58 int m1; /**< Some documentation for member 'm1'... 59 * Multiple lines ... Note the "multi-line" here refers 60 * to the code. Whether it is displayed in multiple lines 61 * on the specific HTML page depends on the browser rendering. 62 * 63 * @note We can also embed note for member 'm1'... 64 */ 65 int m2; /**< Some documentation for member 'm2'... */ 66 int m3; /**< Some documentation for member 'm3'... */ 67 int m4; /**< Some documentation for member 'm4'... */ 68 int m5; /**< Some documentation for member 'm5'... */ 69 }; 70 71 /** 72 * @brief Brief description this structure 73 * 74 * Detailed description starts here, one line or multiple lines. 75 * Blah blah blah... 76 * 77 * @note This is a note for this structure, blah blah blah... 78 */ 79 struct dogygen_example_struct_another 80 { 81 /** Some documentation for member 'm1'... */ 82 int (*m1)(int *param1, int param2, int param3, int param4); 83 /** Some documentation for member 'm2'... */ 84 int (*m2)(int *param1, int param2, int param3, int param4); 85 }; 86 87 /** 88 * @brief Brief description this structure 89 * 90 * Detailed description starts here, one line or multiple lines. 91 * Blah blah blah... 92 * 93 * @note This is a note for this structure, blah blah blah... 94 */ 95 struct dogygen_example_struct_another2 96 { 97 /** 98 * @brief Brief description of m1 99 * @param param1 The first param. 100 * @param param2 The second param. 101 * @param param3 The third param. 102 * @param param4 The fourth param. 103 * @return the operation status, 0 on successful 104 */ 105 int (*m1)(int *param1, int param2, int param3, int param4); 106 /** 107 * @brief Brief description of m2 108 * @param param1 The first param. 109 * @param param2 The second param. 110 * @param param3 The third param. 111 * @param param4 The fourth param. 112 * @return the operation status, 0 on successful 113 */ 114 int (*m2)(int *param1, int param2, int param3, int param4); 115 }; 116 117 /** @} */ 118 119 #endif /* _DOXYGEN_EXAMPLE_STRUCT_H_ */ 120