Affichage des commentaires d'utilisation dans les fonctions destinées à être utilisées de manière interactive

J'ai un certain nombre de fonctions définies dans mon .bashrc, destinées à être utilisées de manière interactive dans un terminal. Je les ai généralement précédés d'un commentaire décrivant son utilisation prévue:

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

C'est bien si vous parcourez le code source, mais il est agréable de l'exécuter typedans le terminal pour obtenir un rappel rapide de ce que fait la fonction. Cependant, cela (naturellement) ne comprend pas de commentaires:

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

Ce qui m'a fait penser "ce ne serait pas bien si ce genre de commentaires persistait pour typepouvoir les afficher?" Et dans l'esprit des docstrings de Python, j'ai trouvé ceci:

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

Maintenant, l'utilisation est incluse dans la typesortie! Bien sûr, comme vous pouvez le voir, la citation devient un problème qui pourrait être source d'erreurs, mais c'est une expérience utilisateur plus agréable quand cela fonctionne.

Donc ma question est, est-ce une idée terrible? Existe-t-il de meilleures alternatives (comme les fonctions man/ infopour) pour fournir aux utilisateurs des fonctions Bash un contexte supplémentaire?

Idéalement, j'aimerais toujours que les instructions d'utilisation soient situées à proximité de la définition de la fonction afin que les personnes qui consultent le code source bénéficient également de l'avantage, mais s'il existe un moyen "approprié" de le faire, je suis ouvert à des alternatives.

Modifier ce sont toutes des fonctions de style d'assistance assez simples et je cherche juste à obtenir un peu de contexte supplémentaire de manière interactive. Certes, pour les scripts plus complexes qui analysent les indicateurs, j'ajouterais une --helpoption, mais pour ceux-ci, il serait quelque peu fastidieux d'ajouter des indicateurs d'aide à tout. C'est peut-être juste un coût que je devrais accepter, mais ce :hack semble fonctionner assez bien sans rendre la source beaucoup plus difficile à lire notre montage.

Je ne pense pas qu'il existe une seule bonne façon de procéder.

De nombreuses fonctions, scripts et autres exécutables fournissent un message d'aide si l'utilisateur fournit -hou --helpen option:

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

Par exemple:

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

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