shunk031-shdoc-shell-docs

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

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.

使用此技能可让Shell脚本注释被

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
```
以了解最小标签集、简洁示例和外部参考策略。