doxygen: improve howto

- Add description on how to group macros.
- Add description for structs on how to write comments
  for members when the name of member is too.
- Use @ref to link group instead of the html filenames.

Signed-off-by: Chen Wang <[email protected]>

6 files changed, 81 insertions, 29 deletions

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 @@
  * <a href="https://github.com/RT-Thread/rt-thread/blob/master/documentation/0.doxygen/example/include/enum.h">documentation/0.doxygen/example/include/enum.h</a>
  * for code example.
  *
- * See
- * <a href="./group__group__doxygen__example__enum.html">Doxygen Example of Enumeration</a>
- * 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 @@
  * <a href="https://github.com/RT-Thread/rt-thread/blob/master/documentation/0.doxygen/example/include/groups.h">documentation/0.doxygen/example/include/groups.h</a>
  * for code example.
  *
- * See
- * <a href="./group__group__doxygen__example__sub.html">Doxygen Example of Groups and Sub-Groups</a>
- * for html output.
+ * See @ref group_doxygen_example for html output.
  *
  * More information can be found in the Doxygen manual:
  * <a href="https://www.doxygen.nl/manual/grouping.html">Grouping</a>.
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 @@
  *   <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>
  *   for code example.
  *
- * See
- * <a href="./group__group__doxygen__example__macro.html">Doxygen Example of Macro</a>
- * 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
+ * <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>
+ * 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
  * <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>
  * for code example.
  *
- * See
- * <a href="./group__group__doxygen__example__struct.html">Doxygen Example of Structure</a>
- * 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 @@
  * <a href="https://github.com/RT-Thread/rt-thread/blob/master/documentation/0.doxygen/example/include/typedef.h">documentation/0.doxygen/example/include/typedef.h</a>
  * for code example.
  *
- * See
- * <a href="./group__group__doxygen__example__typedef.html">Doxygen Example of Typedef</a>
- * 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 @@
  * <a href="https://github.com/RT-Thread/rt-thread/blob/master/documentation/0.doxygen/example/include/union.h">documentation/0.doxygen/example/include/union.h</a>
  * for code example.
  *
- * See
- * <a href="./group__group__doxygen__example__union.html">Doxygen Example of Union</a>
- * for html output.
+ * See @ref group_doxygen_example_union for html output.
  */
 
 /**