インタラクティブに使用することを目的とした関数での使用法コメントの表示

私は、.bashrcターミナルでインタラクティブに使用することを意図して、いくつかの関数を定義しています。私は通常、それらの前に、その使用目的を説明するコメントを付けます。

# Usage: foo [bar]
# Foo's a bar into a baz
foo() {
  ...
}

これは、ソースコードを参照する場合は問題ありtypeませんが、関数が何を実行するかをすばやく思い出させるためにターミナルで実行すると便利です。ただし、これには（当然のことながら）コメントは含まれていません。

$ type foo
foo is a function
foo ()
{
    ...
}

「このようなコメントtypeが表示され、表示されるようになっていたらいいのではないか」と私は思いました。そして、Pythonのdocstringsの精神で私はこれを思いつきました：

foo() {
  : Usage: foo [bar]
  : "Foo's a bar into a baz"
  ...
}

$ type foo
foo is a function
foo ()
{
    : Usage: foo [bar];
    : "Foo's a bar into a baz";
    ...
}

これで、使用法がtype出力に含まれます。もちろん、あなたが見ることができるように、引用はエラーが発生しやすい問題になる可能性がありますが、それが機能するとき、それはより良いユーザーエクスペリエンスです。

だから私の質問は、これはひどい考えですか？Bash関数のユーザーに追加のコンテキストを提供するための（関数のman/のような）より良い代替手段はありinfoますか？

ソースコードを見ている人にも利益が得られるように、使用説明書を関数定義の近くに配置することが理想ですが、これを行うための「適切な」方法がある場合は、代替手段を受け入れます。

編集これらはすべて非常に単純なヘルパースタイルの関数であり、私は対話的に少し余分なコンテキストを取得していますよ。確かに、フラグを解析するより複雑なスクリプトの--help場合はオプションを追加しますが、これらの場合はすべてにヘルプフラグを追加するのがやや面倒です。多分それは私が受け入れるべきコストだろうが、この:ハックはソースを私たちの編集を読みにくくすることなく、かなりうまくいくようです。

これを行う良い方法は1つだけだとは思いません。

多くの関数、スクリプト、およびその他の実行可能ファイルは、ユーザーが提供した場合、-hまたは--helpオプションとして、ヘルプメッセージを提供します。

$ foo() {
[[ "$1" =~ (-h|--help) ]] && { cat <<EOF
Usage: foo [bar]
Foo's a bar into a baz
EOF
return;
}
: ...other stuff...
}

例えば：

$ foo -h
Usage: foo [bar]
Foo's a bar into a baz

$ foo --help
Usage: foo [bar]
Foo's a bar into a baz