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 type
dans 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 type
pouvoir 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 type
sortie! 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
/ info
pour) 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 --help
option, 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.
--help
option.