shunk031-shellscript-shdoc-docs

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

[!NOTE] After reading this
SKILL.md
, say:
🐚 I read shunk031-shellscript-shdoc-docs.

[!NOTE] 阅读此
SKILL.md
后，说：
🐚 I read shunk031-shellscript-shdoc-docs.

Shdoc Shell Docs

Shdoc Shell 文档

Overview

概述

Use this skill to make shellscript comments parseable by

shdoc

without bloating simple code with boilerplate. Inspect the file first, then document the script and the non-trivial functions that benefit from generated reference docs.

使用此 skill，使 shellscript 注释能够被

shdoc

解析，同时避免用样板代码让简单脚本变得冗长。先检查文件，然后为脚本以及适合生成参考文档的非平凡函数编写文档。

Workflow

工作流程

Inspect the target shell file before writing comments.
Read
```
references/shdoc-rules.md
```
before editing comments.
Use
```
install/common/mise.sh
```
as the repo-local style example when working in this repository.
Add or repair file-level annotations near the top of the file:
- Prefer
```
@file
```
  for the script identifier.
- Add
```
@brief
```
  for a single-sentence summary.
- Add multiline
```
@description
```
  only when the script needs more context.
Add function-level annotations only where they help:
- Start with
```
@description
```
  .
- Add
```
@arg
```
  for positional parameters.
- Add
```
@option
```
  for flags and option-value pairs.
- Add
```
@example
```
  when the call shape is not obvious.
- Add
```
@stdout
```
  ,
```
@stderr
```
  ,
```
@exitcode
```
  , or
```
@see
```
  only when they clarify observable behavior.
Rewrite existing free-form comments into valid
```
shdoc
```
annotations instead of keeping two parallel comment styles.

编写注释前检查目标 shell 文件。
编辑注释前阅读
```
references/shdoc-rules.md
```
。
在此仓库中工作时，使用
```
install/common/mise.sh
```
作为仓库内样式示例。
在文件顶部附近添加或修复文件级注解：
- 脚本标识符优先使用
```
@file
```
  。
- 添加
```
@brief
```
  作为一句话摘要。
- 仅当脚本需要更多上下文时，添加多行
```
@description
```
  。
仅在有助于理解的地方添加函数级注解：
- 以
```
@description
```
  开始。
- 使用
```
@arg
```
  描述位置参数。
- 使用
```
@option
```
  描述标志以及选项和值对。
- 当调用方式不直观时，添加
```
@example
```
  。
- 仅当
```
@stdout
```
  、
```
@stderr
```
  、
```
@exitcode
```
  或
```
@see
```
  有助于说明可观察行为时添加它们。
将现有的自由格式注释重写为有效的
```
shdoc
```
注解，不要保留两套并行的注释风格。

Review Checklist

审查清单

Confirm the docs match the implementation instead of guessing arguments or options.
Keep annotations immediately above the file header or function they describe.
Prefer behavior and operator-facing intent over internal implementation notes.
Skip boilerplate comments for trivial private helpers unless the user asks for exhaustive coverage.
Keep multiline annotation blocks compact and easy to render as Markdown.

确认文档与实现一致，不要猜测参数或选项。
将注解紧邻其描述的文件头或函数上方。
优先描述行为和操作者意图，而非内部实现细节。
除非用户要求全面覆盖，否则不要为简单的私有辅助函数添加样板注释。
保持多行注解块紧凑，便于渲染为 Markdown。

References

参考资料

Read
```
references/shdoc-rules.md
```
for the minimal tag set, concise examples, and external reference policy.

阅读
```
references/shdoc-rules.md
```
，了解最小标签集、精简示例和外部引用策略。