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

Question

Eu tenho um número de funções definidas no meu .bashrc , com a intenção de ser usado interativamente em um terminal. Eu geralmente os precedi com um comentário descrevendo seu uso pretendido:

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

Isto é bom se estiver navegando no código-fonte, mas é legal rodar type no terminal para ter 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 que type pudesse exibi-los?" E no espírito das docstrings do Python, surgiu:

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 diretamente na saída type ! É claro que, como você pode ver, cotar se torna um problema que pode ser propenso a erros, mas é uma experiência de usuário mais agradável quando funciona.

Então, minha pergunta é, esta é uma idéia terrível? Existem alternativas melhores (como man / info para funções) para fornecer aos usuários de funções Bash um contexto adicional?

O ideal é que eu ainda queira que as instruções de uso sejam localizadas perto da 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 "correta" de fazê-lo, estou aberto a alternativas. / p>

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

    

Answer 1

Eu não acho que haja 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 -h ou --help como 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