diff --git a/documentation/0.doxygen/example/include/enum.h b/documentation/0.doxygen/example/include/enum.h index a4a9cd5352..0d85e77729 100644 --- a/documentation/0.doxygen/example/include/enum.h +++ b/documentation/0.doxygen/example/include/enum.h @@ -16,9 +16,7 @@ * documentation/0.doxygen/example/include/enum.h * for code example. * - * See - * Doxygen Example of Enumeration - * for html output. + * See @ref group_doxygen_example_enum for html output. */ /** diff --git a/documentation/0.doxygen/example/include/groups.h b/documentation/0.doxygen/example/include/groups.h index 71ea20d83c..c8592f15d8 100644 --- a/documentation/0.doxygen/example/include/groups.h +++ b/documentation/0.doxygen/example/include/groups.h @@ -26,9 +26,7 @@ * documentation/0.doxygen/example/include/groups.h * for code example. * - * See - * Doxygen Example of Groups and Sub-Groups - * for html output. + * See @ref group_doxygen_example for html output. * * More information can be found in the Doxygen manual: * Grouping. diff --git a/documentation/0.doxygen/example/include/macro.h b/documentation/0.doxygen/example/include/macro.h index b849909eb5..d1432b4395 100644 --- a/documentation/0.doxygen/example/include/macro.h +++ b/documentation/0.doxygen/example/include/macro.h @@ -20,9 +20,14 @@ * documentation/0.doxygen/example/include/macro.h * for code example. * - * See - * Doxygen Example of Macro - * for html output. + * We often categorize macros in our code. Similarly, when writing doxygen + * comments for these categorized macros, we can also group them. See + * `DOXYGEN_EXAMPLE_GROUP_A_X`/`DOXYGEN_EXAMPLE_GROUP_A_Y` and + * `DOXYGEN_EXAMPLE_GROUP_B_X`/`DOXYGEN_EXAMPLE_GROUP_B_Y` in + * documentation/0.doxygen/example/include/macro.h + * for code example. + * + * See @ref group_doxygen_example_macro for html output. */ /** @@ -47,6 +52,28 @@ */ #define DOXYGEN_EXAMPLE_ABS(x) (((x)>0)?(x):-(x)) +/** + * @defgroup group_doxygen_example_macro_group_a Group A of Macros + * + * @brief Doxygen Example of Macros grouped in A. + * + * @{ + */ +#define DOXYGEN_EXAMPLE_GROUP_A_X 0x0000 /**< Description of X in group A */ +#define DOXYGEN_EXAMPLE_GROUP_A_Y 0x0001 /**< Description of Y in group A */ +/** @} */ + +/** + * @defgroup group_doxygen_example_macro_group_b Group B of Macros + * + * @brief Doxygen Example of Macros grouped in B + * + * @{ + */ +#define DOXYGEN_EXAMPLE_GROUP_B_X 0x0000 /**< Description of X in group B */ +#define DOXYGEN_EXAMPLE_GROUP_B_Y 0x0001 /**< Description of Y in group B */ +/** @} */ + /** @} */ #endif diff --git a/documentation/0.doxygen/example/include/struct.h b/documentation/0.doxygen/example/include/struct.h index 46f130319d..756ee100d8 100644 --- a/documentation/0.doxygen/example/include/struct.h +++ b/documentation/0.doxygen/example/include/struct.h @@ -15,14 +15,24 @@ * can add a detailed description part, which is also optional. * * Put member comments inside the structure definition and after every member. + * See `struct dogygen_example_struct` for example. + * + * If the structure member is too long (this often happens when the structure + * member is a callback function), when the comment is written after the member, + * it will make the code line too long. In this case, we can also put the comment + * before the member. See `struct dogygen_example_struct_another` for example. + * + * Going a step further, for this kind of structure whose members are callback + * functions, we can describe the members in style for functions, it is more + * complicated and contains more content. It is useful when we want to describe + * the parameters and return values ​​of the callback function in more detail. + * See `struct dogygen_example_struct_another2` for example. * * See * documentation/0.doxygen/example/include/struct.h * for code example. * - * See - * Doxygen Example of Structure - * for html output. + * See @ref group_doxygen_example_struct for html output. */ /** @@ -68,17 +78,40 @@ struct dogygen_example_struct */ struct dogygen_example_struct_another { - int m1; /**< Some documentation for member 'm1'... - * Multiple lines ... Note the "multi-line" here refers - * to the code. Whether it is displayed in multiple lines - * on the specific HTML page depends on the browser rendering. - * - * @note We can also embed note for member 'm1'... - */ - int m2; /**< Some documentation for member 'm2'... */ - int m3; /**< Some documentation for member 'm3'... */ - int m4; /**< Some documentation for member 'm4'... */ - int m5; /**< Some documentation for member 'm5'... */ + /** Some documentation for member 'm1'... */ + int (*m1)(int *param1, int param2, int param3, int param4); + /** Some documentation for member 'm2'... */ + int (*m2)(int *param1, int param2, int param3, int param4); +}; + +/** + * @brief Brief description this structure + * + * Detailed description starts here, one line or multiple lines. + * Blah blah blah... + * + * @note This is a note for this structure, blah blah blah... + */ +struct dogygen_example_struct_another2 +{ + /** + * @brief Brief description of m1 + * @param param1 The first param. + * @param param2 The second param. + * @param param3 The third param. + * @param param4 The fourth param. + * @return the operation status, 0 on successful + */ + int (*m1)(int *param1, int param2, int param3, int param4); + /** + * @brief Brief description of m2 + * @param param1 The first param. + * @param param2 The second param. + * @param param3 The third param. + * @param param4 The fourth param. + * @return the operation status, 0 on successful + */ + int (*m2)(int *param1, int param2, int param3, int param4); }; /** @} */ diff --git a/documentation/0.doxygen/example/include/typedef.h b/documentation/0.doxygen/example/include/typedef.h index 2232f31bc6..ba8216d0dd 100644 --- a/documentation/0.doxygen/example/include/typedef.h +++ b/documentation/0.doxygen/example/include/typedef.h @@ -28,9 +28,7 @@ * documentation/0.doxygen/example/include/typedef.h * for code example. * - * See - * Doxygen Example of Typedef - * for html output. + * See @ref group_doxygen_example_typedef for html output. */ #include "struct.h" diff --git a/documentation/0.doxygen/example/include/union.h b/documentation/0.doxygen/example/include/union.h index 9dbf2e4744..7062fc6c93 100644 --- a/documentation/0.doxygen/example/include/union.h +++ b/documentation/0.doxygen/example/include/union.h @@ -16,9 +16,7 @@ * documentation/0.doxygen/example/include/union.h * for code example. * - * See - * Doxygen Example of Union - * for html output. + * See @ref group_doxygen_example_union for html output. */ /** diff --git a/documentation/0.doxygen/example/src/function.c b/documentation/0.doxygen/example/src/function.c index 289c09b2ce..98b2007dea 100644 --- a/documentation/0.doxygen/example/src/function.c +++ b/documentation/0.doxygen/example/src/function.c @@ -45,9 +45,7 @@ * documentation/0.doxygen/example/src/function.c * for code example. * - * See - * Doxygen Example of Function - * for html output. + * See @ref group_doxygen_example_function for html output. * * @note documentation/0.doxygen/example/src/function.h * is just an example of the header file where we declare the API without