Отображение комментариев об использовании в функциях, предназначенных для интерактивного использования

У меня есть несколько функций, определенных в моем .bashrc, предназначенных для интерактивного использования в терминале. Я обычно предшествовал им с комментарием, описывающим его предполагаемое использование:

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

Это хорошо, если вы просматриваете исходный код, но приятно запускать typeв терминале, чтобы получить быстрое напоминание о том, что делает функция. Однако это (понятно) не включает комментарии:

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

Что заставило меня задуматься: "Не было бы неплохо, если бы такие комментарии сохранялись, чтобы их typeможно было отображать?" И в духе строк документации Python я придумал это:

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

Теперь использование включено прямо в typeвывод! Конечно, как вы можете видеть, цитирование становится проблемой, которая может быть подвержена ошибкам, но это приятнее для пользователя, когда оно работает.

Итак, мой вопрос, это ужасная идея? Существуют ли лучшие альтернативы (например, функции man/ infoдля) для предоставления пользователям функций Bash дополнительного контекста?

В идеале мне бы хотелось, чтобы инструкции по использованию располагались рядом с определением функции, чтобы люди, просматривающие исходный код, также получали выгоду, но если есть «правильный» способ сделать это, я открыт для альтернатив.

Отредактируйте все эти довольно простые вспомогательные функции, и я просто хочу получить немного дополнительного контекста в интерактивном режиме. Конечно, для более сложных скриптов, которые разбирают флаги, я бы добавил --helpопцию, но для них было бы несколько обременительно добавлять флаги помощи ко всему. Возможно, это просто цена, которую я должен принять, но этот :хак, кажется, работает достаточно хорошо, не делая исходный текст намного сложнее для чтения нашего редактирования.

Я не думаю, что есть только один хороший способ сделать это.

Многие функции, сценарии и другие исполняемые файлы предоставляют справочное сообщение, если пользователь предоставляет -hили --helpв качестве опции:

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

Например:

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

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