linux - Bash スクリプトのドキュメント スタイルの標準は何ですか?

Question

私は現在、いくつかの関数を含む Bash スクリプトを作成しており、ドキュメントを追加して、他のチーム メンバーが関数のポイントを理解できるようにしたいと考えています。

Bashスクリプトとそれに含まれる機能を文書化するための標準的な「スタイル」はありますか?

Answer 1

古い質問への回答を追加していることは理解していますが、最近ツールが改善されたと感じており、この質問を見ている他の人を助けるために追加の提案をしたいと思います.

最近、シェル スクリプトで TomDoc スタイルのコメントを使用する TomDoc.sh を見つけました。提供されたツールは、情報を抽出し、マークダウンまたはプレーン テキスト ドキュメントを生成できます。

他のツールも存在します。 BashDocは JavaDoc 構文をモデルにしており、さまざまなタグをサポートしています。RoboDocでは、C スタイルのコメントを Bash コードに埋め込むと、必要な情報が抽出されます。最後に、Apple はシェル スクリプトにHeaderDocを使用しています。これら 3 つすべてに、コメントの推奨スタイルがあります。

ドキュメントを生成するだけでなく、コードに注釈を付けたい場合は、shocco.shを使用することをお勧めします。特定の形式はなく、実行中のシェル コマンドを説明する人間が読めるテキストを表示するように設計されています。

Answer 2

通常、私は C などの他の言語で使用するガイドラインに類似したガイドラインに従うようにしています。

これには、以下を含む関数ヘッダーが含まれます。

• 関数名、簡単な説明、および目的
• 説明付きの引数と戻り値のリスト
• すべての副作用のリスト (変数やファイルの変更など)

Answer 3

私の理解では、Bash doc の標準はありません。ただし、通常は次のようにします。

• あなたの名前、著作権、連絡先、およびスクリプトの簡単な内容を含むヘッダーをbashファイルに含めます
• 関数を起動して使用する方法を説明する usage() 関数。
• 関数が何をするかを説明するための各関数の上部のコメント。