doxygen: add documentation for doxygen

Documentation is provided to clarify how to write
doxygen documentation for RT-Thread. This document
is also integrated as part of RT-Thread doxygen
documentation.

An example is also provided.

The original README.md is removed and integrated into
this document.

Updated github actions for doxygen too.

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

8 files changed, 431 insertions, 0 deletions

diff --git a/documentation/0.doxygen/example/include/enum.h b/documentation/0.doxygen/example/include/enum.h
new file mode 100644
index 0000000000..14fda47b08
--- /dev/null
+++ b/documentation/0.doxygen/example/include/enum.h
@@ -0,0 +1,37 @@
+#ifndef _DOXYGEN_EXAMPLE_ENUM_H_
+#define _DOXYGEN_EXAMPLE_ENUM_H_
+
+/**
+ * @page page_howto_enum How to write doxygen documentation for enumeration.
+ *
+ * A comment block before the enumeration definition is recommended to
+ * describe the general information of the enumeration type. In the
+ * comment block, a `@brief` is required, other commands (such as `@note`)
+ * are optional.
+ *
+ * To describe the values of the enumeration, document is recommended
+ * to be put after each value.
+ *
+ * See
+ * <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 example.
+ */
+
+/**
+ * @addtogroup group_doxygen_example
+ */
+
+/** @{ */
+
+/**
+ * @brief Brief description of this enumeration
+ */
+enum doxygen_example_enum
+{
+    V1, /**< description for value 1 */
+    V2, /**< description for value 2 */
+};
+
+/** @} */
+
+#endif /* _DOXYGEN_EXAMPLE_ENUM_H_ */
diff --git a/documentation/0.doxygen/example/include/function.h b/documentation/0.doxygen/example/include/function.h
new file mode 100644
index 0000000000..5b414240df
--- /dev/null
+++ b/documentation/0.doxygen/example/include/function.h
@@ -0,0 +1,7 @@
+#ifndef _DOXYGEN_EXAMPLE_FUNCTION_H_
+#define _DOXYGEN_EXAMPLE_FUNCTION_H_
+
+void doxygen_example_func_foo(int a, int b);
+int doxygen_example_func_bar(int a, int* b);
+
+#endif /* _DOXYGEN_EXAMPLE_FUNCTION_H_ */
diff --git a/documentation/0.doxygen/example/include/groups.h b/documentation/0.doxygen/example/include/groups.h
new file mode 100644
index 0000000000..04b14d43fc
--- /dev/null
+++ b/documentation/0.doxygen/example/include/groups.h
@@ -0,0 +1,74 @@
+#ifndef _DOXYGEN_EXAMPLE_GROUPS_H_
+#define _DOXYGEN_EXAMPLE_GROUPS_H_
+
+/**
+ * @page page_howto_groups How to use groups in doxygen documentation.
+ *
+ * Doxygen has three mechanisms to group things together. For RT-Thread
+ * API documentation, we use 'topics' to create new page for each group.
+ * On HTML browser, the topics pages are shown under the "Modules" in the
+ * treeview on the left.
+ *
+ * To define a group, we use `@defgroup` command. The group name should be
+ * prefixed with a "group_", and the group name should be unique. We can
+ * define a group anywhere, not necessarily in the same file as the members
+ * of the group. Generally, we define a group in a header file.
+ *
+ * To make an entity (structure, function etc. or another group) a member of
+ * a speicific group, we can use `@ingroup` command and put the `@ingroup`
+ * command inside its documentation block.
+ *
+ * To avoid putting `@ingroup` commands in the documentation for each member
+ * you can use `@addtogroup` and group members together by the open marker
+ * `@{` before the group and the closing marker `@}` after the group.
+ *
+ * See
+ * <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 example.
+ *
+ * More information can be found in the Doxygen manual:
+ * <a href="https://www.doxygen.nl/manual/grouping.html">Grouping</a>.
+ */
+
+/**
+ * @defgroup group_doxygen_example_sub Sub Group of Doxygen Example
+ *
+ * All members of this group will be displayed in one HTML page.
+ *
+ * @ingroup group_doxygen_example
+ *
+ * @brief Define a sub group of Doxygen Example.
+ */
+
+/**
+ * @brief Brief description of this enumeration
+ *
+ * We use `@ingroup` to add this enum to the group_doxygen_example_sub separately.
+ *
+ * @ingroup group_doxygen_example_sub
+ */
+enum doxygen_example_enum_2
+{
+    V1, /**< description for value 1 */
+    V2, /**< description for value 2 */
+};
+
+// This entity is not a member of any group.
+#define DOXYGEN_EXAMPLE_CONST_E 300 /**< Description of macro const D */
+
+/**
+ * @addtogroup group_doxygen_example_sub
+ */
+
+/** @{ */
+
+/*
+ * DOXYGEN_EXAMPLE_CONST_C & DOXYGEN_EXAMPLE_CONST_D are close together, so
+ * we can use `@addtogroup`, `@{` and `@}` to group them together.
+ */
+#define DOXYGEN_EXAMPLE_CONST_C 100 /**< Description of macro const C */
+#define DOXYGEN_EXAMPLE_CONST_D 200 /**< Description of macro const D */
+
+/** @} */
+
+#endif /* _DOXYGEN_EXAMPLE_GROUPS_H_ */
diff --git a/documentation/0.doxygen/example/include/macro.h b/documentation/0.doxygen/example/include/macro.h
new file mode 100644
index 0000000000..a5c1d7f352
--- /dev/null
+++ b/documentation/0.doxygen/example/include/macro.h
@@ -0,0 +1,44 @@
+#ifndef _DOXYGEN_EXAMPLE_MACRO_H_
+#define _DOXYGEN_EXAMPLE_MACRO_H_
+
+/**
+ * @page page_howto_macro How to write doxygen documentation for macro.
+ *
+ * There are two typical types of macro definitions.
+ *
+ * - One is to define constant macros. For this type of macro, we
+ *   recommend putting documentation after members. See `DOXYGEN_EXAMPLE_CONST_A`
+ *   and `DOXYGEN_EXAMPLE_CONST_B` 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 exmaple.
+ *
+ * - The other is to define macros with parameters. For this type of
+ *   macro, we recommend using a method similar to documenting for
+ *   functions, that is, writing comment block before the macro definition.
+ *   More details please see @ref page_howto_function
+ *   See `DOXYGEN_EXAMPLE_ABS` 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 example.
+ */
+
+/**
+ * @addtogroup group_doxygen_example
+ */
+
+/** @{ */
+
+#define DOXYGEN_EXAMPLE_CONST_A 100 /**< Description of macro const A */
+#define DOXYGEN_EXAMPLE_CONST_B 200 /**< Description of macro const B */
+
+/**
+ * @brief Computes the absolute value of its argument @a x.
+ *
+ * @param[in] x input value.
+ *
+ * @return absolute value of @a x.
+ */
+#define DOXYGEN_EXAMPLE_ABS(x) (((x)>0)?(x):-(x))
+
+/** @} */
+
+#endif
diff --git a/documentation/0.doxygen/example/include/struct.h b/documentation/0.doxygen/example/include/struct.h
new file mode 100644
index 0000000000..528e85487a
--- /dev/null
+++ b/documentation/0.doxygen/example/include/struct.h
@@ -0,0 +1,78 @@
+#ifndef _DOXYGEN_EXAMPLE_STRUCT_H_
+#define _DOXYGEN_EXAMPLE_STRUCT_H_
+
+/**
+ * @page page_howto_struct How to write doxygen documentation for structure.
+ *
+ * We recommend the following approach:
+ *
+ * A comment block before the structure definition is recommended to
+ * describe the general information of the structure type. In the
+ * comment block, a `@brief` is required, other commands (such as `@note`)
+ * are optional.
+ *
+ * If you feel that the description of `@brief` is not enough, you
+ * can add a detailed description part, which is also optional.
+ *
+ * Put member comments inside the structure definition and after every member.
+ *
+ * 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 example.
+ */
+
+/**
+ * @addtogroup group_doxygen_example
+ */
+
+/** @{ */
+
+/**
+ * @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
+{
+    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'... */
+};
+
+/**
+ * @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_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'... */
+};
+
+/** @} */
+
+#endif /* _DOXYGEN_EXAMPLE_STRUCT_H_ */
diff --git a/documentation/0.doxygen/example/include/typedef.h b/documentation/0.doxygen/example/include/typedef.h
new file mode 100644
index 0000000000..eeb004fb5b
--- /dev/null
+++ b/documentation/0.doxygen/example/include/typedef.h
@@ -0,0 +1,59 @@
+#ifndef _DOXYGEN_EXAMPLE_TYPEDEF_H_
+#define _DOXYGEN_EXAMPLE_TYPEDEF_H_
+
+/**
+ * @page page_howto_typedef How to write doxygen documentation for typedef.
+ *
+ * It is recommended to use separate typedef statements rather
+ * than a combination. That is:
+ *
+ * Recommended:
+ *
+ * ```c
+ * struct S { ... };
+ * typedef struct S S_t;
+ * ```
+ *
+ * Not recommended:
+ *
+ * ```c
+ * typedef struct S { ... } S_t;
+ * ```
+ *
+ * The reason is we found that the former is more readable, and when we
+ * write comment block with `@typedef`, the latter may
+ * cause unexpceted behaviour for doxygen (as of version 1.9.1).
+ *
+ * See
+ * <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 example.
+ */
+
+#include "struct.h"
+#include "enum.h"
+
+/**
+ * @addtogroup group_doxygen_example
+ */
+
+/** @{ */
+
+/**
+ * @typedef dogygen_example_struct_t
+ * Alias of `struct dogygen_example_struct`.
+ *
+ * @typedef dogygen_example_struct_another_t
+ * Alias of `struct dogygen_example_struct_another`.
+ */
+typedef struct dogygen_example_struct dogygen_example_struct_t;
+typedef struct dogygen_example_struct_another dogygen_example_struct_another_t;
+
+/**
+ * @typedef doxygen_example_enum
+ * Alias of `enum doxygen_example_enum`.
+ */
+typedef enum doxygen_example_enum doxygen_example_enum_t;
+
+/** @} */
+
+#endif /* _DOXYGEN_EXAMPLE_TYPEDEF_H_ */
diff --git a/documentation/0.doxygen/example/include/union.h b/documentation/0.doxygen/example/include/union.h
new file mode 100644
index 0000000000..1af9f13ef2
--- /dev/null
+++ b/documentation/0.doxygen/example/include/union.h
@@ -0,0 +1,37 @@
+#ifndef _DOXYGEN_EXAMPLE_UNION_H_
+#define _DOXYGEN_EXAMPLE_UNION_H_
+
+/**
+ * @page page_howto_union How to write doxygen documentation for union.
+ *
+ * A comment block before the union definition is recommended to
+ * describe the general information of the union type. In the
+ * comment block, a `@brief` is required, other commands (such as `@note`)
+ * are optional.
+ *
+ * To describe the values of the union, document is recommended
+ * to be put after each value.
+ *
+ * See
+ * <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 example.
+ */
+
+/**
+ * @addtogroup group_doxygen_example
+ */
+
+/** @{ */
+
+/**
+ * @brief Brief description of this union
+ */
+union doxygen_example_union
+{
+    int    v1; /**< description for v1 */
+    double v2; /**< description for v2 */
+};
+
+/** @} */
+
+#endif /* _DOXYGEN_EXAMPLE_UNION_H_ */
diff --git a/documentation/0.doxygen/example/src/function.c b/documentation/0.doxygen/example/src/function.c
new file mode 100644
index 0000000000..6ac5dc90de
--- /dev/null
+++ b/documentation/0.doxygen/example/src/function.c
@@ -0,0 +1,95 @@
+/**
+ * @page page_howto_function How to write doxygen documentation for function.
+ *
+ * Function comments can be placed in the header file (before the
+ * function declaration) OR in the source file (before the function
+ * definition).
+ *
+ * The advantage of placing it in the header file is that we generally
+ * think that the header file is the place to declare the API, but the
+ * problem is that when a module has many API extern functions, if the
+ * comments are placed in the header file, the header file will be very
+ * long. You can imagine that for a module with many APIs and many
+ * comments, the header file will be full of large green comments, and
+ * the function declaration part is mixed in the middle and difficult
+ * to distinguish. And if you want to fully understand which extern
+ * functions this module exports, you need to scroll a long file for a
+ * long time to get a general idea. Especially for RTT, see `include/rtthread.h`
+ * as an example.
+ *
+ * Putting the comment in the source file can avoid the above problems.
+ * For developers, it is also convenient to read the comments together with
+ * the code implementation. The disadvantage is that it would be different
+ * from the function side, from other types, such as structures, i.e. the API
+ * comments of functions need to be read in the source file instead of directly
+ * in the header file.
+ *
+ * Comprehensive consideration can be combined with the actual situation.
+ * For example, if there are too many API functions in a header file, it is
+ * recommended to put the function comments in the source file.
+ *
+ * So, it is **strongly recommended** to put comments in the source file when
+ * writing new functions or annotating functions.
+ *
+ * To documenting for functions, a comment block before the function
+ * declaraion/definition is recommended to describe the general information
+ * of the function. In the comment block, a `@brief` is required, a `@return`
+ * is also required no matter if the function return values or not. `@param` is
+ * required if any, and if it is provided, direction [in]/[out]/[in,out] should
+ * be provide together. Other commands (such as `@note`) are optional.
+ *
+ * If you feel that the description of `@brief` is not enough, you
+ * can add a detailed description part, which is also optional.
+ *
+ * See
+ * <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>
+ * for example.
+ *
+ * <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> is an example of the header file where we just declare the API without doxygen documentation.
+ */
+
+/**
+ * @addtogroup group_doxygen_example
+ */
+
+/** @{ */
+
+/**
+ * @brief Brief description for the function
+ *
+ * Detailed description starts here, one line or multiple lines.
+ * Blah blah blah...
+ *
+ * @param[in] a Description of param a
+ *
+ * @param[in] b Description of param b
+ *
+ * @return void
+ *
+ * @note This is a note for this structure, blah blah blah...
+ */
+void doxygen_example_func_foo(int a, int b)
+{
+    return;
+}
+
+/**
+ * @brief Brief description for the function
+ *
+ * Detailed description starts here, one line or multiple lines.
+ * Blah blah blah...
+ *
+ * @param[in] a Description of param a
+ *
+ * @param[out] b Description of param b
+ *
+ * @return the return value, 0 for success, -1 for failure
+ *
+ * @note This is a note for this structure, blah blah blah...
+ */
+int doxygen_example_func_bar(int a, int* b)
+{
+    return 0;
+}
+
+/** @} */