Anzeigen von Nutzungskommentaren in Funktionen, die interaktiv verwendet werden sollen

Ich habe eine Reihe von Funktionen in meinem .bashrcdefiniert, die interaktiv in einem Terminal verwendet werden sollen. Ich habe ihnen im Allgemeinen einen Kommentar vorangestellt, in dem die beabsichtigte Verwendung beschrieben wird:

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

Dies ist in Ordnung, wenn Sie den Quellcode durchsuchen, aber es ist schön, typeim Terminal ausgeführt zu werden, um eine schnelle Erinnerung an die Funktionsweise der Funktion zu erhalten. Dies beinhaltet jedoch (verständlicherweise) keine Kommentare:

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

Was mich zum Nachdenken brachte: "Wäre es nicht schön, wenn diese Art von Kommentaren fortbestehen würde, damit typesie angezeigt werden könnten?" Und im Geiste von Pythons Docstrings habe ich mir Folgendes ausgedacht :

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

Jetzt ist die Nutzung direkt in der enthalten type Ausgabe enthalten! Wie Sie sehen, wird das Zitieren natürlich zu einem Problem, das fehleranfällig sein kann, aber es ist eine schönere Benutzererfahrung, wenn es funktioniert.

Meine Frage ist also, ist das eine schreckliche Idee? Gibt es bessere Alternativen (wie ein man/ infofür Funktionen), um Benutzern von Bash-Funktionen zusätzlichen Kontext bereitzustellen?

Idealerweise möchte ich immer noch, dass sich die Gebrauchsanweisungen in der Nähe der Funktionsdefinition befinden, damit die Benutzer des Quellcodes ebenfalls den Vorteil erhalten. Wenn es jedoch einen "richtigen" Weg gibt, bin ich offen für Alternativen.

Bearbeiten Sie diese sind alles ziemlich einfache Funktionen im Helfer-Stil und ich möchte nur interaktiv einen zusätzlichen Kontext erhalten. Sicherlich würde ich für komplexere Skripte, die Flags analysieren, eine --helpOption hinzufügen , aber für diese wäre es etwas mühsam, allen Hilfe-Flags hinzuzufügen. Vielleicht ist das nur ein Preis, den ich akzeptieren sollte, aber dieser :Hack scheint ziemlich gut zu funktionieren, ohne dass die Quelle viel schwieriger zu lesen ist.

Ich glaube nicht, dass es nur einen guten Weg gibt, dies zu tun.

Viele Funktionen, Skripte und andere ausführbare Dateien bieten eine Hilfemeldung, wenn der Benutzer -hoder --helpals Option Folgendes bereitstellt :

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

Beispielsweise:

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

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