Exibindo comentários de uso em funções destinadas a serem usadas interativamente

Eu tenho várias funções definidas no meu .bashrc, destinadas a serem usadas interativamente em um terminal. Geralmente, eu os precedia com um comentário descrevendo o uso pretendido:

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

Isso é bom se você estiver navegando no código-fonte, mas é bom rodar typeno terminal para obter um lembrete rápido do que a função faz. No entanto, isso (compreensivelmente) não inclui comentários:

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

O que me fez pensar "não seria legal se esse tipo de comentário persistisse para typepoder exibi-lo?" E no espírito das doutrinas de Python, eu vim com isso:

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

Agora, o uso está incluído na typesaída! Obviamente, como você pode ver, a citação se torna um problema que pode ser propenso a erros, mas é uma experiência melhor do usuário quando funciona.

Então, minha pergunta é: essa é uma péssima idéia? Existem alternativas melhores (como funções a man/ infopara) para fornecer aos usuários das funções do Bash um contexto adicional?

Idealmente, eu ainda gostaria que as instruções de uso estivessem localizadas próximas à definição da função, para que as pessoas que visualizam o código-fonte também obtenham o benefício, mas se houver uma maneira "adequada" de fazer isso, estou aberto a alternativas.

Editar estas são todas as funções de estilo auxiliar bastante simples e só estou procurando obter um pouco de contexto extra interativamente. Certamente, para scripts mais complexos que analisam sinalizadores, eu adicionaria uma --helpopção, mas para esses seria um pouco oneroso adicionar sinalizadores de ajuda a tudo. Talvez seja apenas um custo que devo aceitar, mas esse :hack parece funcionar razoavelmente bem sem tornar a fonte muito mais difícil de ler nossa edição.

Não acho que exista apenas uma boa maneira de fazer isso.

Muitas funções, scripts e outros executáveis ​​fornecem uma mensagem de ajuda se o usuário fornecer -hou --helpcomo uma opção:

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

Por exemplo:

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

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