diff --git a/.trae/skills/chinese-commenter/SKILL.md b/.trae/skills/chinese-commenter/SKILL.md new file mode 100644 index 0000000..0a17408 --- /dev/null +++ b/.trae/skills/chinese-commenter/SKILL.md @@ -0,0 +1,182 @@ +--- +name: "chinese-commenter" +description: "Adds detailed Chinese comments to C source files in a project. Invoke when user wants to add Chinese documentation to their embedded project code." +--- + +# Chinese Commenter Skill + +## Overview + +This skill automatically adds detailed Chinese comments to C source files in an embedded project. It enhances code readability and maintainability by adding: + +- Function descriptions and parameter explanations +- Variable and struct comments +- Section headers for better organization +- Technical notes and usage instructions + +## Supported File Types + +- `.c` - C source files +- `.h` - Header files + +## Usage Guidelines + +### 1. Basic Usage + +To add Chinese comments to a single file: + +```text +1. Use Read tool to get the file content: + Read("d:/project/src/main.c") + +2. Analyze the code structure and identify: + - Functions and their purposes + - Key variables and data structures + - Code sections and logical blocks + +3. Use Edit tool to add comments: + Edit("d:/project/src/main.c", "old_code", "new_code_with_comments") +``` + +### 2. Processing Multiple Files + +To process all files in a project: + +```text +1. Use Glob to find all C files: + Glob("**/*.c", "d:/project/src") + +2. Iterate through each file and add comments: + For each file: + - Read the file content + - Add Chinese comments to functions, variables, and sections + - Use Edit tool to apply changes +``` + +### 3. Comment Standards + +Follow these commenting standards: + +#### File Header +```c +/** + ************************************************************************** + * @file filename.c + * @brief 文件功能描述 + * @details 详细说明文件的用途和实现 + ************************************************************************** + */ +``` + +#### Function Comments +```c +/** + * @brief 函数功能描述 + * @param param1: 参数1说明 + * @param param2: 参数2说明 + * @retval 返回值说明 + * @note 注意事项 + */ +``` + +#### Section Headers +```c +/* ==================== 功能模块名称 ==================== */ +``` + +#### Variable Comments +```c +uint32_t counter; /* 计数器:记录某种状态 */ +``` + +## Example Workflow + +### Step 1: Explore Project Structure + +```text +LS("d:/Trae_space/嵌入式开发/byd_qin_ev 1.4/project/src") +Glob("**/*.c", "d:/Trae_space/嵌入式开发/byd_qin_ev 1.4/project/src") +``` + +### Step 2: Process Main File + +```text +Read("d:/Trae_space/嵌入式开发/byd_qin_ev 1.4/project/src/main.c") + +Edit("d:/Trae_space/嵌入式开发/byd_qin_ev 1.4/project/src/main.c", + "int main(void)", + "/**\n * @brief 主函数入口\n * @param none\n * @retval none\n */\nint main(void)") +``` + +### Step 3: Process Driver Files + +```text +Read("d:/Trae_space/嵌入式开发/byd_qin_ev 1.4/project/src/wk_can.c") + +Edit("d:/Trae_space/嵌入式开发/byd_qin_ev 1.4/project/src/wk_can.c", + "void wk_can1_init(void)", + "/**\n * @brief CAN1初始化函数\n * @param none\n * @retval none\n * @note CAN1工作在监听模式,用于侦听车辆CAN总线数据\n */\nvoid wk_can1_init(void)") +``` + +## Best Practices + +1. **Understand Code First**: Always read the file completely before adding comments +2. **Be Descriptive**: Explain *why* as well as *what* the code does +3. **Follow Standards**: Maintain consistent comment style throughout the project +4. **Update Regularly**: Keep comments in sync when code changes +5. **Avoid Redundancy**: Don't repeat what the code already clearly shows +6. **Use Chinese**: Write comments in clear, concise Chinese + +## Common Patterns + +### CAN Driver Comments + +```c +/* ==================== GPIO配置 ==================== */ +/* ==================== CAN基础配置 ==================== */ +/* ==================== 波特率配置 ==================== */ +/* ==================== 过滤器配置 ==================== */ +/* ==================== 中断配置 ==================== */ +``` + +### FreeRTOS Task Comments + +```c +/** + * @brief 任务函数名称 + * @param pvParameters: 任务参数 + * @retval none + * @note 任务优先级:X,堆栈大小:Y字节 + */ +``` + +### System Initialization Comments + +```c +/** + * @brief 系统初始化函数 + * @param none + * @retval none + * @details 执行顺序: + * 1. 时钟配置 + * 2. 外设初始化 + * 3. 中断配置 + * 4. 应用任务启动 + */ +``` + +## When to Invoke This Skill + +- User asks to add comments to C code +- User wants to improve code documentation +- User needs to document an embedded project +- Before sharing code with team members +- When preparing code for review or handover + +## Notes + +- This skill works best with embedded C projects +- Always preserve the original code functionality +- Comments should enhance, not obscure, the code +- Use appropriate technical terminology in Chinese +- Keep comments concise but informative \ No newline at end of file