182 lines
4.8 KiB
Markdown
182 lines
4.8 KiB
Markdown
---
|
||
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 |