Mostrar comentarios de uso en funciones destinadas a ser utilizadas interactivamente

Tengo una serie de funciones definidas en mi .bashrc, con la intención de ser utilizadas de forma interactiva en un terminal. Generalmente los precedí con un comentario que describe su uso previsto:

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

Esto está bien si navega por el código fuente, pero es bueno ejecutarlo typeen la terminal para obtener un recordatorio rápido de lo que hace la función. Sin embargo, esto (comprensiblemente) no incluye comentarios:

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

Lo que me hizo pensar "¿no sería bueno si este tipo de comentarios persistieran para typepoder mostrarlos?" Y en el espíritu de las cadenas de documentos de Python se me ocurrió esto:

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

Ahora el uso se incluye en el mismo typela salida! Por supuesto, como puede ver, las citas se convierten en un problema que podría ser propenso a errores, pero es una experiencia de usuario más agradable cuando funciona.

Entonces mi pregunta es, ¿es esta una idea terrible? ¿Existen mejores alternativas (como las funciones a man/ infopara) para proporcionar a los usuarios de las funciones de Bash un contexto adicional?

Idealmente, todavía me gustaría que las instrucciones de uso se ubicaran cerca de la definición de la función para que las personas que vean el código fuente también obtengan el beneficio, pero si hay una forma "adecuada" de hacerlo, estoy abierto a alternativas.

Editar estas son funciones de estilo auxiliar bastante simples y solo estoy buscando obtener un poco de contexto adicional de forma interactiva. Ciertamente, para secuencias de comandos más complejas que analizan indicadores, agregaría una --helpopción, pero para estos sería un poco pesado agregar indicadores de ayuda a todo. Quizás sea solo un costo que debería aceptar, pero este :truco parece funcionar razonablemente bien sin hacer que la fuente sea mucho más difícil de leer.

No creo que haya una buena manera de hacer esto.

Muchas funciones, scripts y otros ejecutables proporcionan un mensaje de ayuda si el usuario proporciona -ho --helpcomo una opción:

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

Por ejemplo:

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

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