EV-Embedded-Control-System/.trae/skills/chinese-commenter/SKILL.md

---
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