Visualizzazione dei commenti sull'utilizzo in funzioni destinate all'uso interattivo

Ho un numero di funzioni definite nel mio .bashrc, intese per essere utilizzate in modo interattivo in un terminale. In genere li ho preceduti con un commento che descrive l'uso previsto:

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

Questo va bene se si sfoglia il codice sorgente, ma è bello eseguirlo typenel terminale per ottenere un rapido promemoria di ciò che fa la funzione. Tuttavia questo (comprensibilmente) non include commenti:

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

Il che mi ha fatto pensare "non sarebbe bello se questo tipo di commenti persistesse in modo da typepoterli visualizzare?" E nello spirito delle dotstring di Python ho pensato a questo:

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

Ora l'utilizzo è incluso proprio typenell'output! Ovviamente, come puoi vedere, la citazione diventa un problema che potrebbe essere soggetto a errori, ma è un'esperienza utente migliore quando funziona.

Quindi la mia domanda è: è un'idea terribile? Esistono alternative migliori (come una man/ infoper funzioni) per fornire agli utenti delle funzioni Bash un contesto aggiuntivo?

Idealmente, mi piacerebbe comunque che le istruzioni per l'uso si trovassero vicino alla definizione della funzione in modo che anche le persone che visualizzano il codice sorgente ne traggano vantaggio, ma se esiste un modo "corretto" per farlo sono aperto alle alternative.

Modifica queste sono tutte funzioni in stile helper abbastanza semplici e sto solo cercando di ottenere un po 'di contesto in più interattivamente. Certamente per gli script più complessi che analizzano i flag aggiungerei --helpun'opzione, ma per questi sarebbe un po 'oneroso aggiungere flag di aiuto a tutto. Forse è solo un costo che dovrei accettare, ma questo :trucco sembra funzionare abbastanza bene senza rendere la fonte molto più difficile da leggere la nostra modifica.

Non penso che ci sia solo un buon modo per farlo.

Molte funzioni, script e altri eseguibili forniscono un messaggio di aiuto se l'utente fornisce -ho --helpcome opzione:

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

Per esempio:

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

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