Optimize Article

Author: OasisPioneer

source/Language Core/Chapter-2/Section-01.md

@@ -20,7 +20,7 @@
 int age = 18;
 ```
 
-由于单行注释的特性也可以将其写在某行代码的后方，具体使用场景为定义了多个变量需要描述解释。
+由于单行注释的特性，也可以将其写在某行代码的后方，具体使用场景为定义了多个变量需要描述解释。
 
 ```{tip}
 为了让代码看起来更加的整洁美观，我们通常会使用 `Tab` 键来让代码或注释缩进使其与上下行的代码垂直对齐。
@@ -48,15 +48,19 @@ int Addition(int A, int B) {
 }
 ```
 
-如果在开发过程中你需要临时屏蔽某些代码但又不想删除的时候也可以使用注释来进行屏蔽。
+```{attention}
+C++ 中的多行注释不能嵌套使用，即不能在一个 `/* */` 注释内部再使用另一个 `/* */` 注释。
+```
+
+如果在开发过程中你需要临时屏蔽某些代码但又不想删除的时候，也可以使用注释来进行屏蔽。
 
 ```CPP
 // int C = A + B;
 ```
 
-## 高级注释
+## 文档注释
 
-在普通注释的基础上高级注释可以使用特殊工具如 `Doxygen` 提取 C++ 的代码和对应的 `Doxygen` 注释编译成一个在线文档能够让开发者在无需翻阅大量代码的前提下精准的找到自己想要查看的代码的对应描述，同时高级注释语法支持将整个代码文件进行注释描述。
+在普通注释的基础上，文档注释可以使用特殊工具如 Doxygen 提取 C++ 的代码和对应的注释，编译成一个在线文档，能够让开发者在无需翻阅大量代码的前提下精准地找到自己想要查看的代码的对应描述。同时，高级注释语法支持将整个代码文件进行注释描述。
 
 ### 代码文件注释
 
@@ -72,6 +76,20 @@ int Addition(int A, int B) {
  */
 ```
 
+### 常用 Doxygen 标签
+
+| 标签       | 用途         | 示例                                                                 |
+| :--------- | :----------- | :------------------------------------------------------------------- |
+| `@file`    | 文件名       | `@file main.cpp`                                                     |
+| `@brief`   | 简要描述     | `@brief Main function of the program`                                |
+| `@details` | 详细描述     | `@details This function initializes the system and starts the main loop` |
+| `@param`   | 参数说明     | `@param value The input value to process`                            |
+| `@return`  | 返回值说明   | `@return The result of the calculation`                              |
+| `@note`    | 注意事项     | `@note This function must be called before initialization`           |
+| `@warning` | 警告信息     | `@warning This function may throw exceptions`                        |
+| `@author`  | 作者信息     | `@author John Doe`                                                    |
+| `@date`    | 日期         | `@date 2023-01-01`                                                   |
+
 更多高级注释语法可以前往 `Doxygen` 官网 <https://www.doxygen.nl/manual/index.html> 查看官方文档
 
 ## 提醒注释
@@ -94,15 +112,17 @@ int Addition(int A, int B) {
 | **NOTE**   | **笔记/说明**：用于对某段复杂的代码进行解释或提供额外信息，帮助他人理解。                         | `// NOTE: 这里使用位运算是为了提高性能`       |
 
 ```{Attention}
-并不是所有的开发工具都支持提醒注释，具体是否能用还要在你的开发工具上进行对应的测试。
+不同的开发工具对提醒注释的支持程度不同，有些工具仅支持基本的 `TODO`，而有些工具支持更多类型并提供高级功能（如任务列表、跳转等）。具体支持情况需要在你的开发工具上进行测试。
 ```
 
 ## 注释规则
 
 编写代码注释时候通常需要遵守以下几个默认行为规范。
 
-**实时注释**: 当你对代码进行了改动请确保注释也进行对应的更新，防止出现注释与代码的实际功能有差异。
+**实时更新**: 当你对代码进行了改动，请确保注释也进行对应的更新，防止出现注释与代码的实际功能有差异。过时的注释比没有注释更糟糕。
 
 **表明实意**: 注释应该表达代码无法直接传递的实际意思，而不是重复的表达代码的内容。
 
-**注释方案**: 在大型项目中尽量使用 Doxygen 注释语法，这样做的好处就是能够提升注释的可读性也可编译成项目文档。
+**注释方案**: 在大型项目中尽量使用 Doxygen 注释语法，这样做的好处就是能够提升注释的可读性也可编译成项目文档。
+
+**适度注释**: 不要为每一行代码都添加注释，这会增加维护负担。只在必要的地方添加注释，解释 "为什么" 而不是 "是什么"。