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

У мене є ряд функцій, визначених у моїх .bashrc, призначених для інтерактивного використання в терміналі. Я, як правило, передував їм із коментарем із описом його використання:

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

Це добре, якщо переглядати вихідний код, але приємно запустити typeв терміналі, щоб отримати швидке нагадування про те, що функція виконує. Однак це (зрозуміло) не включає коментарі:

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

Що наштовхнуло мене на думку "чи не було б добре, якби такі коментарі зберігалися, щоб вони typeмогли відображати їх?" І в дусі доктрин Пітона я придумав це:

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