shunk031-shellscript-shdoc-docs

说明

阅读此 SKILL.md 后，请说：🐚 I read shunk031-shellscript-shdoc-docs.

Shdoc Shell 文档

概述

使用此技能，让 shellscript 注释可由 shdoc 解析，同时避免用样板内容使简单代码变得臃肿。先检查文件，再为脚本和适合生成参考文档的重要函数编写文档。

工作流

1. 编写注释前，先检查目标 shell 文件。
2. 编辑注释前，阅读 references/shdoc-rules.md。
3. 在此代码库中工作时，使用 install/common/mise.sh 作为仓库本地的风格示例。
4. 在文件顶部附近添加或修复文件级注解：
   • 优先使用 @file 指定脚本标识符。
   • 使用 @brief 添加一句话摘要。
   • 仅在脚本需要更多背景信息时，添加多行 @description。
5. 仅在有帮助时添加函数级注解：
   • 以 @description 开头。
   • 为位置参数添加 @arg。
   • 为标志和选项值对添加 @option。
   • 调用形式不明显时，添加 @example。
   • 仅在有助于说明可观察行为时，添加 @stdout、@stderr、@exitcode 或 @see。
6. 将现有的自由格式注释改写为有效的 shdoc 注解，不要保留两种并行的注释风格。

审查清单

• 确认文档与实际实现相符，不要臆测参数或选项。
• 将注解紧贴在其描述的文件头或函数上方。
• 优先说明行为和面向操作者的意图，而非内部实现细节。
• 除非用户要求全面覆盖，否则跳过对简单私有辅助函数的样板注释。
• 保持多行注解块简洁，便于渲染为 Markdown。

参考资料

• 阅读 references/shdoc-rules.md，了解最少标签集、简洁示例和外部参考政策。