shunk031-shellscript-shdoc-docs

用途

本技能用于编写和审查 shell 脚本的 shdoc 注释文档。它适用于编码智能体创建、编辑或审查 .sh 文件或 shell 可执行文件的场景，目标是让 shell 脚本注释能够被 shdoc 解析，同时避免用样板注释让简单代码变得臃肿。

主要能力

• 为 shell 脚本添加或修复文件级注解，包括：
  • 优先使用 @file 作为脚本标识符；
  • 使用 @brief 添加一句话摘要；
  • 仅在脚本需要更多上下文时添加多行 @description。
• 为函数添加函数级注解，仅在确有帮助时使用：
  • 从 @description 开始；
  • 使用 @arg 描述位置参数；
  • 使用 @option 描述标志和选项-值对；
  • 当调用形式不明显时使用 @example；
  • 仅在有助于说明可观察行为时使用 @stdout、@stderr、@exitcode 或 @see。
• 将已有的自由格式注释改写为有效的 shdoc 注解，而不是保留两套并行的注释风格。

使用方式

工作流程如下：

1. 在编写注释前先检查目标 shell 文件。
2. 在编辑注释前阅读 references/shdoc-rules.md。
3. 在本仓库中工作时，使用 install/common/mise.sh 作为仓库本地风格示例。
4. 在文件顶部附近添加或修复文件级注解。
5. 仅在确有帮助处添加函数级注解。
6. 将已有自由格式注释改写为有效的 shdoc 注解。

审查清单

• 确认文档与实现一致，而不是猜测参数或选项。
• 保持注解紧贴其所描述的文件头或函数上方。
• 优先描述行为与面向操作者的意图，而非内部实现说明。
• 对简单的私有辅助函数跳过样板注释，除非用户要求详尽覆盖。
• 保持多行注解块紧凑，并易于渲染为 Markdown。

参考资料

阅读 references/shdoc-rules.md 可获取最小标签集、简洁示例和外部参考策略。

限制

资料中未提供关于收费、价格、平台支持范围、具体效果或额外使用步骤的信息，暂未提供。