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 <unicorn_wang@outlook.com>

.github/workflows/doxygen.yml

@@ -4,25 +4,27 @@ on:
     branches:
       - master
     paths:
-      - 'documentation/doxygen/**'
+      - 'documentation/**'
       - 'src/**'
       - 'include/**'
+      - 'components/finsh/**'
       - 'components/drivers/include/drivers/**'
-      - 'components/dfs/dfs_v2/include/**'
+      - 'components/drivers/clk/**'
       - 'components/dfs/dfs_v2/src/**'
-      - 'components/finsh/**'
+      - 'components/dfs/dfs_v2/include/**'
       - '.github/workflows/doxygen.yml'
   # Runs at 16:00 UTC (BeiJing 00:00) on the 30st of every month
   push:
     branches: [master]
     paths:
-      - 'documentation/doxygen/**'
+      - 'documentation/**'
       - 'src/**'
       - 'include/**'
+      - 'components/finsh/**'
       - 'components/drivers/include/drivers/**'
-      - 'components/dfs/dfs_v2/include/**'
+      - 'components/drivers/clk/**'
       - 'components/dfs/dfs_v2/src/**'
-      - 'components/finsh/**'
+      - 'components/dfs/dfs_v2/include/**'
       - '.github/workflows/doxygen.yml'
   schedule:
     - cron:  '0 16 30 * *'

documentation/0.doxygen/INDEX.md

@@ -0,0 +1,116 @@
+@page howto_doxygen How to write doxygen documentation for RT-Thread
+
+RT-Thread Online Documentation is created based on doxygen and is available at: <https://rt-thread.github.io/rt-thread/>. It is consisted of two parts.
+
+One part is the detailed introduction of Kernel, which is written in markdown format and converted into HTML page by doxygen. It is displayed under "RT-Thread User Guide" in Treeview on the left side of the browser. Each sub-chapter is organized into a hierarchical structure by using doxygen's [subpage mechanism][2]. There are no special requirements for writing this part, so I will not go into details in this article.
+
+The other part is the description of API. RT-Thread uses [doxygen][1] to automate the generation of documentation from source code comments, parsing information about classes, functions, and variables to produce output in format of HTML. It is displayed under "Modules" in Treeview on the left side of the browser. Each sub-chapter is organized into a hierarchical structure by using doxygen's [topics mechanism][3]. The main content of this article is to describe how to write API with doxygen.
+
+# General Rules on writing API documentation
+
+@note The code comments and HTML content generated by doxygen in this guide, for the **structures**, **constants(macro definition)**, **enumeration values**, **union values**, **global functions**, **global variables** and other objects involved are all within the scope of the **RT-Thread kernel API**. The code of internal functions, variables (such as static functions etc.) are not belong to the API scope, how to write comment for these elements are not considered in this guide.
+
+By default, API documentation is written in header files, but there are exceptions, such as for **functions**.
+
+There are several ways to mark a comment block as a detailed description. We prefer JavaDoc-style (C-style) comment block with some additional markings to document the code, like this:
+
+```
+/**
+ * ... text ...
+ */
+```
+
+When you want to put documentation after members, we prefer a Qt style, like this:
+
+```
+int var; /**< Detailed description after the member */
+```
+
+When writing comments based on doxygen, several commands defined by doxygen are used. See <https://www.doxygen.nl/manual/commands.html> for more details about doxygen commands.
+
+More details refer to [Doxygen Docs: Documenting the code][4]
+
+# Detailed Rules on writing API documentation
+
+This article provide an <a href="https://github.com/RT-Thread/rt-thread/blob/master/documentation/0.doxygen/example/">example</a>. 
+
+Click @ref group_doxygen_example for the corresponding HTML documentation that is generated by Doxygen.
+
+The contents of Example are described in the following chapters:
+
+- @subpage page_howto_groups
+
+- @subpage page_howto_macro
+
+- @subpage page_howto_struct
+
+- @subpage page_howto_union
+
+- @subpage page_howto_enum
+
+- @subpage page_howto_typedef
+
+- @subpage page_howto_function
+
+# Build & Run
+
+## How to build & run doxygen html on Ubuntu
+
+The following steps are verified on Ubuntu 22.04：
+
+```shell
+$ lsb_release -a
+No LSB modules are available.
+Distributor ID:	Ubuntu
+Description:	Ubuntu 22.04.5 LTS
+Release:	22.04
+Codename:	jammy
+```
+
+The following packages (and dependents) need to be installed:
+
+```shell
+$ sudo apt update
+$ sudo apt install doxygen
+$ sudo apt install graphviz
+```
+
+Assume that the path of RT-Thead code tree is $RTT, execute the following command to build html.
+
+```shell
+$ cd $RTT/documentation
+$ rm -rf html
+$ doxygen
+```
+
+A new html directory will be created and all the html files will be placed in this directory.
+
+If you want to quickly browse HTML locally (in Ubuntu environment), you can enter the html directory and start a local HTML server through Python.
+
+```shell
+$ cd html
+$ python3 -m http.server
+Serving HTTP on 0.0.0.0 port 8000 (http://0.0.0.0:8000/) ...
+```
+
+A bash script `run.sh` is provided to automatic upon operations.
+
+```shell
+$ cd $RTT/documentation
+$ ./run.sh
+```
+
+Then open the browser and enter `http://<IP>:8000/index.html` to access the created html web pages. If it is a local access, then `<IP>` should be replaced by `localhost`. If it is a remote access, then `<IP>` should be replaced by the actual accessible IP address of the machine where HTML is located.
+
+## How to build & run doxygen html with Doxywizard
+
+1. download from https://doxygen.nl/index.html
+2. open `Doxywizard`
+3. `File` -> `Open`
+4. Open the file ./Doxyfile 
+5.  To tab `Run` , Click `Run doxygen`
+
+[1]:https://www.doxygen.nl/
+[2]:https://www.doxygen.nl/manual/grouping.html#subpaging
+[3]:https://www.doxygen.nl/manual/grouping.html#topics
+[4]:https://www.doxygen.nl/manual/docblocks.html

documentation/0.doxygen/doxygen.h

@@ -0,0 +1,9 @@
+/*
+ * This file is only used for doxygen document generation.
+ */
+
+/**
+ * @defgroup group_doxygen_example Doxygen Example
+ *
+ * @brief Introduce how to write doxygen documentation.
+ */

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_ */

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_ */

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_ */

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

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_ */

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_ */

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_ */

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;
+}
+
+/** @} */

documentation/7.contribution/INDEX.md

@@ -6,4 +6,6 @@ We sincerely thank you for your contribution, and welcome to submit the code thr
 
 All the real-time operating system kernel and open source components can be used free of charge for commercial products, there is no potential commercial risk and you will not being request to publish application source.
 
-@subpage rtt_code_style_en
+@subpage rtt_code_style_en
+
+@subpage howto_doxygen

documentation/Doxyfile

@@ -921,7 +921,6 @@ RECURSIVE              = YES
 # run.
 
 EXCLUDE                = ./0.doxygen/mainpage.h \
-                         ./README.md \
                          ./2.quick-start/quick_start_qemu \
                          ./env/env-vscode.md \
                          ./contribution_guide/coding_style_cn.md

documentation/README.md

@@ -1,55 +0,0 @@
-# How to build doxygen html
-
-1. download from https://doxygen.nl/index.html
-2. open `Doxywizard`
-3. `File` -> `Open`
-4. Open the file ./Doxyfile 
-5.  To tab `Run` , Click `Run doxygen`
-
-# How to build & run doxygen html on Ubuntu
-
-The following steps are verified on Ubuntu 22.04：
-
-```shell
-$ lsb_release -a
-No LSB modules are available.
-Distributor ID:	Ubuntu
-Description:	Ubuntu 22.04.5 LTS
-Release:	22.04
-Codename:	jammy
-```
-
-The following packages (and dependents) need to be installed:
-
-```shell
-$ sudo apt update
-$ sudo apt install doxygen
-$ sudo apt install graphviz
-```
-
-Assume that the path of RT-Thead code tree is $RTT, execute the following command to build html.
-
-```shell
-$ cd $RTT/documentation
-$ rm -rf html
-$ doxygen
-```
-
-A new html directory will be created and all the html files will be placed in this directory.
-
-If you want to quickly browse HTML locally (in Ubuntu environment), you can enter the html directory and start a local HTML server through Python.
-
-```shell
-$ cd html
-$ python3 -m http.server
-Serving HTTP on 0.0.0.0 port 8000 (http://0.0.0.0:8000/) ...
-```
-
-A bash script `run.sh` is provided to automatic upon operations.
-
-```shell
-$ cd $RTT/documentation
-$ ./run.sh
-```
-
-Then open the browser and enter `http://<IP>:8000/index.html` to access the created html web pages. If it is a local access, then `<IP>` should be replaced by `localhost`. If it is a remote access, then `<IP>` should be replaced by the actual accessible IP address of the machine where HTML is located.