【更新】更新描述

Author: yangjie11

documentation/coding_style_cn.md

@@ -121,30 +121,59 @@ int rt_hw_spi_init(void)
 
 **函数注释**：
 
-- 以 `/**` 开头，以 `  */` 结尾，中间写入函数注释
-- 第一部分：一个段落介绍函数的作用
-- 第二部分：参数采用 @param + 参数 + 介绍参数 的方式
-- 第三部分：返回采用 @return + 返回值 + 介绍返回值 的方式
-- 以上每个部分之间空一行
+注释以 `/**` 开头，以 `  */` 结尾，中间写入函数注释，组成元素如下，每个元素描述之间空一行，且首列对齐：
+
+- @brief + 简述函数作用。在描述中，着重说明该函数的作用，每句话首字母大写，句尾加英文句号。
+- @note + 函数说明。在上述简述中未能体现到的函数功能或作用的一些点，可以做解释说明，每句话首字母大写，句尾加英文句号。
+- @see + 相关 API 罗列。若有与当前函数相关度较高的 API，可以进行列举。
+- @param + 以参数为主语 + be 动词 + 描述，说明参数的意义或来源。
+- @return + 枚举返回值 + 返回值的意思，若返回值为数据，则直接介绍数据的功能。
+- @warning + 函数使用注意要点。在函数使用时，描述需要注意的事项，如使用环境、使用方式等。每句话首字母大写，句尾加英文句号。
+
+注释模版请参见：rt-thread/src/ipc.c 源码文件，英文注释请参考使用 grammarly 以及谷歌翻译。
 
 ```C
 /**
- * This function will initialize a semaphore and put it under control of
- * resource management.
+ * @brief    The function will initialize a static event object.
+ *
+ * @note     For the static event object, its memory space is allocated by the compiler during compiling,
+ *           and shall placed on the read-write data segment or on the uninitialized data segment.
+ *           By contrast, the rt_event_create() function will allocate memory space automatically
+ *           and initialize the event.
+ *
+ * @see      rt_event_create()
+ *
+ * @param    event is a pointer to the event to initialize. It is assumed that storage for the event
+ *           will be allocated in your application.
+ *
+ * @param    name is a pointer to the name that given to the event.
+ *
+ * @param    value is the initial value for the event.
+ *           If want to share resources, you should initialize the value as the number of available resources.
+ *           If want to signal the occurrence of an event, you should initialize the value as 0.
+ *
+ * @param    flag is the event flag, which determines the queuing way of how multiple threads wait
+ *           when the event is not available.
+ *           The event flag can be ONE of the following values:
+ *
+ *               RT_IPC_FLAG_PRIO          The pending threads will queue in order of priority.
  *
- * @param sem the semaphore object
- * @param name the name of semaphore
- * @param value the initial value of semaphore
- * @param flag the flag of semaphore
+ *               RT_IPC_FLAG_FIFO          The pending threads will queue in the first-in-first-out method
+ *                                         (also known as first-come-first-served (FCFS) scheduling strategy).
  *
- * @return the operation status, RT_EOK on successful
+ *               NOTE: RT_IPC_FLAG_FIFO is a non-real-time scheduling mode. It is strongly recommended to
+ *               use RT_IPC_FLAG_PRIO to ensure the thread is real-time UNLESS your applications concern about
+ *               the first-in-first-out principle, and you clearly understand that all threads involved in
+ *               this event will become non-real-time threads.
+ *
+ * @return   Return the operation status. When the return value is RT_EOK, the initialization is successful.
+ *           If the return value is any other values, it represents the initialization failed.
+ *
+ * @warning  This function can ONLY be called from threads.
  */
-rt_err_t rt_sem_init(rt_sem_t    sem,
-                     const char *name,
-                     rt_uint32_t value,
-                     rt_uint8_t  flag)
+rt_err_t rt_event_init(rt_event_t event, const char *name, rt_uint8_t flag)
 {
-	....
+   ... 
 }
 ```
 
@@ -159,8 +188,7 @@ rt_err_t rt_sem_init(rt_sem_t    sem,
     }
 ```
 
-唯一的例外是 switch 语句，switch-case 语句采用 case 语句与 switch 对齐的方式，
-例如：
+唯一的例外是 switch 语句，switch-case 语句采用 case 语句与 switch 对齐的方式，例如：
 
 ```c
     switch (value)
@@ -249,9 +277,15 @@ rt_timer + 动词短语的形式表示能够应用于 timer 对象的方法。
 
 在创建一个新的对象时，应该思考好，对象的内存操作处理：是否允许一个静态对象存在，或仅仅支持从堆中动态分配的对象。
 
-## 14.用 astyle 自动格式化代码
+## 14.格式化代码
+
+格式化代码是指通过脚本自动整理你的代码，并使其符合 RT-Thread 的编码规范。本文提供以下两种自动格式化代码方法，可以自行选择或配合使用。
+
+### 使用 astyle 格式化
+
+用 astyle 自动格式化代码，参数如下：
 
-    参数：--style=allman
+          --style=allman
           --indent=spaces=4
           --indent-preproc-block
           --pad-oper
@@ -262,3 +296,13 @@ rt_timer + 动词短语的形式表示能够应用于 timer 对象的方法。
           --lineend=linux
           --convert-tabs
           --verbose
+
+能满足函数空格、缩进、函数语句等的规范。
+
+### 使用 formatting 格式化
+
+使用 [formatting](https://github.com/mysterywolf/formatting) 扫描文件来格式化代码：formatting 可以满足编码规则的基本要求，如：
+
+- 将源文件编码统一为 UTF-8
+- 将 TAB 键替换为 4 空格
+- 将每行末尾多余的空格删除，并统一换行符为 '\n'