shunk031-shellscript-shdoc-docs

メモ

この SKILL.md を読んだら、次のように言ってください：🐚 I read shunk031-shellscript-shdoc-docs.

Shdoc シェルスクリプトのドキュメント

概要

このスキルを使うと、シンプルなコードを定型文で肥大化させることなく、シェルスクリプトのコメントを shdoc で解析できる形式にできます。まずファイルを確認してから、スクリプトと、生成されるリファレンスドキュメントが役立つ複雑な関数をドキュメント化してください。

ワークフロー

1. コメントを書く前に、対象のシェルファイルを確認します。
2. コメントを編集する前に、references/shdoc-rules.md を読みます。
3. このリポジトリで作業する場合は、リポジトリ内のスタイル例として install/common/mise.sh を使用します。
4. ファイルの先頭付近に、ファイルレベルの注釈を追加または修正します。
   • スクリプトの識別子には @file を優先して使用します。
   • 1 文の要約には @brief を追加します。
   • スクリプトに補足説明が必要な場合に限り、複数行の @description を追加します。
5. 役立つ場合に限り、関数レベルの注釈を追加します。
   • @description から始めます。
   • 位置パラメーターには @arg を追加します。
   • フラグやオプションと値の組み合わせには @option を追加します。
   • 呼び出し方が自明でない場合は @example を追加します。
   • 観測可能な動作を明確にする場合に限り、@stdout、@stderr、@exitcode、または @see を追加します。
6. 既存の自由形式のコメントは、2 種類のコメント形式を併用せず、有効な shdoc 注釈に書き換えます。

レビューチェックリスト

• 引数やオプションを推測せず、ドキュメントが実装と一致していることを確認します。
• 注釈は、説明するファイルヘッダーまたは関数のすぐ上に配置します。
• 内部実装の説明よりも、動作やオペレーター向けの意図を優先します。
• ユーザーから網羅的な説明を求められていない限り、単純なプライベートヘルパーへの定型的なコメントは省略します。
• 複数行の注釈ブロックは簡潔に保ち、Markdown として読みやすく表示できるようにします。

参考資料

• 最小限のタグセット、簡潔な例、外部参照のポリシーについては、references/shdoc-rules.md をお読みください。