GCC

Linux 代码片段注释与分析 Skill 模板（中文、正文无链接）

目标

把一段 Linux C 代码改写成“可独立阅读”的分析稿：保留原码结构与宏，去掉原英文注释，只在需要处补充中文就地注释，并按固定章节输出。

---

输出结构模板

1) 标题

• 用 ## 做大标题
• 大标题只包含：本次片段里会出现 ### 小标题的函数名列表（用空格分隔）
• 函数名列表末尾追加一句概括（不含括号）

示例：

## foo bar baz 同步提交与等待路径梳理

---

2) 大标题下两段（必须有）

作用与实现要点

• 只写策略与设计点，不复述基础流程

• 覆盖这些点（按实际出现取用）：

  • 状态机与状态位流转
  • 分支选择理由（为什么走这条路）
  • 能力门控与特性开关
  • 参数检查与早退路径
  • 一次性标志位/回调绑定
  • 后台机制影响（worker/hrtimer/trace/调度点）

平台关注：单核、无 MMU、ARMv7-M（STM32H750）

• 说明语义是否变化；强调锁/状态位/时间基准/后台机制在该平台的意义

• 若无差异，直接写这一句（原样照抄）：

  • 本段逻辑与单核/无MMU无直接差异，依赖底层 ops 与系统定时机制

---

3) 每个函数的输出模板

每个函数使用：

### 函数名 中文作用

并按下面顺序输出：

1. 函数定义前添加 doxygen 注释块

2. 输出原代码（不省略），但：

   • 删除原英文注释（/* ... */ 与 // ... 都删）
   • 保留宏、类型、结构体字段访问、必要的代码本身

3. 只在需要处添加中文注释（/* ... */），其余不加

---

中文注释写作规则模板

注释写什么

对需要加注释的语句，注释要同时交代（用自然语句写，不用标签词）：

• 这一行做了什么
• 为什么要这样做
• 触发点是什么（什么状态/什么场景下会走到这里）
• 产生什么影响（引用计数、状态位、电源、等待点、资源回收、可见性/顺序性）

避免只写抽象名词（例如“门控/关键路径”这种不落地的词）。

需要加注释的语句范围

出现以下元素时优先加注释（按实际出现取用）：

• 分支选择点（if/else/switch、早退、goto 失败路径）
• 位操作：set_bit/clear_bit/test_bit/test_and_set_bit/test_and_clear_bit
• trace_*、ktime_*、时间戳与超时相关
• worker / workqueue / hrtimer / 定时器回调提交与取消
• 能力门控、特性开关、一次性标志位
• 参数合法性检查、边界值处理
• 等待与唤醒、完成量、队列推进、内存屏障

注释排版与就地解释

单行判断示例形态（注释紧跟判断语句）：

if (cond) /* 解释 cond 表达的状态/门控意义，以及不满足会走向哪里 */
    goto fail;

复合判断分行示例形态（每段就地解释）：

if (a &&  /* 解释 a 表示的状态位/资源是否就绪 */
    b &&  /* 解释 b 的含义，以及它为何需要与 a 同时成立 */
    c)    /* 解释 c 代表的门控/时序点，整体成立会进入哪个分支 */
    return -EINVAL;

关于 goto / 回收 / 等待点的写法

遇到以下语句时，注释必须说明“为什么要这么写，以及避免了什么问题”：

• goto out_*、失败回收路径
• 引用计数增减配平
• 等待点（completion/waitqueue/spin 等待）、唤醒点
• 内存屏障与可见性相关语句

禁用措辞

• 注释里不要出现“关键行”字样
• 分析正文与注释中避免使用“约束”“条件”“后果”等标签化写法（直接用自然语言描述触发点与影响）

---

代码处理规则模板

• 原码完整输出，不省略分支、标签、回收段
• 删除原英文注释
• 不改变量名与控制流，不重排语句（除非为了把复合判断拆行，并保持语义等价）
• 宏、导出符号、结构体声明等保留原样

---

获取上下文与对齐方式模板

• 以 Linux 主线同名文件为主，对照相邻函数与调用链推断语义
• 可用网页检索核对版本差异与命名，但正文不出现任何 URL、链接形态或可点击引用标记
• 通过https://code.googlesource.com/linux/torvalds/linux/+/refs/heads/master进行查看上下文思考
• 如确实需要交代来源信息，放在“对话附注”里，用纯文本描述，不写 URL

---

函数 doxygen 注释块模板（直接套用）

/**
 * @brief 一句话说明该函数做什么（面向调用方的语义）
 * @param xxx 解释参数含义、取值范围、与状态位/资源的关系
 * @return 返回值语义，错误码或状态码代表什么
 *
 * 补充说明：
 * - 说明回调绑定/一次性标志位/等待点与唤醒点之间的关联
 * - 说明与状态位、引用计数、资源生命周期的关系
 */

---

交付输出占位模板（你后续每次都可用）

## <函数A> <函数B> <函数C> <一句概括>

### 作用与实现要点
- ...

### 平台关注：单核、无 MMU、ARMv7-M（STM32H750）
- 本段逻辑与单核/无MMU无直接差异，依赖底层 ops 与系统定时机制

### <函数A> <中文作用>
<doxygen 注释块>
<删掉英文注释后的完整原码 + 中文就地注释>

### <函数B> <中文作用>
...

文章编写

1. 如下是要求写作时使用的skill，请按照此模板进行编写。
2. 不要有人称
3. 需要给出标题
4. 对给的素材内容要做脱敏和去隐私化处理

---
name: 04-process-docs-write
description: 用于撰写/改写文档（Markdown/MDX），强调清晰、面向读者；当需要写 README、设计文档或使用说明时使用。
allowed-tools: Read, Write, Grep, Bash, Glob
---

# Documentation Writing Skill

## When writing documentation

### Start here

1. **Who is this for?** Match complexity to audience. Don't oversimplify hard things or overcomplicate simple ones.
2. **What do they need?** Get them to the answer fast. Nobody wants to be in docs longer than necessary.
3. **What did you struggle with?** Those common questions you had when learning? Answer them (without literally including the question).

### Writing process

**Draft:**

- Write out the steps/explanation as you'd tell a colleague
- Lead with what to do, then explain why
- Use headings that state your point: "Set SAML before adding users" not "SAML configuration timing"

**Edit:**

- Read aloud. Does it sound like you talking? If it's too formal, simplify.
- Cut anything that doesn't directly help the reader
- Check each paragraph has one clear purpose
- Verify examples actually work (don't give examples that error)

**Polish:**

- Make links descriptive (never "here")
- Backticks only for code/variables, **bold** for UI elements
- American spelling, serial commas
- Keep images minimal and scoped tight

**Format:**

- Run prettier on the file after making edits: `yarn prettier --write <file-path>`
- This ensures consistent formatting across all documentation

### Common patterns

**Instructions:**

```markdown
Run:
\`\`\`
command-to-run
\`\`\`

Then:
\`\`\`
next-command
\`\`\`

This ensures you're getting the latest changes.

Not: “(remember to run X before Y…)” buried in a paragraph.

Headings:

• “Use environment variables for configuration” ✅
• “Environment variables” ❌ (too vague)
• “How to use environment variables for configuration” ❌ (too wordy)

Links:

• “Check out the SAML documentation“ ✅
• “Read the docs here“ ❌

Watch out for

• Describing tasks as “easy” (you don’t know the reader’s context)
• Using “we” when talking about Metabase features (use “Metabase” or “it”)
• Formal language: “utilize”, “reference”, “offerings”
• Too peppy: multiple exclamation points
• Burying the action in explanation
• Code examples that don’t work
• Numbers that will become outdated

Quick reference

Write This	Not This
people, companies	users
summarize	aggregate
take a look at	reference
can’t, don’t	cannot, do not
Filter button	`Filter` button
Check out the docs	Click here
```