Menampilkan komentar penggunaan dalam fungsi yang dimaksudkan untuk digunakan secara interaktif

Saya memiliki sejumlah fungsi yang didefinisikan dalam saya .bashrc, bermaksud untuk digunakan secara interaktif di terminal. Saya biasanya mendahului mereka dengan komentar yang menjelaskan tujuan penggunaannya:

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

Ini bagus jika menelusuri kode sumber, tetapi menyenangkan untuk dijalankan typedi terminal untuk mendapatkan pengingat cepat tentang apa yang dilakukan fungsi. Namun ini (dapat dimengerti) tidak termasuk komentar:

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

Yang membuat saya berpikir "bukankah itu baik jika komentar semacam ini bertahan sehingga typebisa menampilkannya?" Dan dalam semangat Python docstrings saya datang dengan ini:

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";
    ...
}

Sekarang penggunaannya sudah termasuk dalam typeoutput! Tentu saja seperti yang Anda lihat mengutip menjadi masalah yang bisa menjadi rawan kesalahan, tetapi itu adalah pengalaman pengguna yang lebih baik ketika berfungsi.

Jadi pertanyaan saya adalah, apakah ini ide yang buruk? Apakah ada alternatif yang lebih baik (seperti man/ infountuk fungsi) untuk menyediakan pengguna fungsi Bash dengan konteks tambahan?

Idealnya saya masih ingin petunjuk penggunaan berada di dekat definisi fungsi sehingga orang yang melihat kode sumber juga mendapatkan manfaatnya, tetapi jika ada cara yang "tepat" untuk melakukan ini, saya terbuka untuk alternatif.

Sunting semua ini adalah fungsi gaya pembantu yang cukup sederhana dan saya hanya ingin mendapatkan konteks ekstra secara interaktif. Tentu saja untuk skrip yang lebih kompleks yang mengurai flag, saya akan menambahkan --helpopsi, tetapi untuk ini akan agak memberatkan untuk menambahkan flag bantuan untuk semuanya. Mungkin itu hanya biaya yang harus saya terima, tetapi :peretasan ini tampaknya bekerja cukup baik tanpa membuat sumber lebih sulit untuk membaca hasil edit kami.

Saya tidak berpikir bahwa hanya ada satu cara yang baik untuk melakukan ini.

Banyak fungsi, skrip, dan executable lainnya menyediakan pesan bantuan jika pengguna menyediakan -hatau --helpsebagai opsi:

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

Sebagai contoh:

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

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