doxygen: add documentation for doxygen

.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