Есть ли соглашение для документирования параметров сценариев оболочки?
Например:
#!/usr/bin/env bash
# <description>
#
# Usage:
# $ ./myScript param1 [param2]
# * param1: <description>
# * param2: <description>
Несколько вещей, которые мне не нравятся в этом конкретном шаблоне:
- имя файла script (
myScript
) появляется внутри самого файла - описание параметра кажется странным
- ведущее пространство до
$
визуально полезно, но может привести к путанице в языках с комментариями блоков, в результате чего некоторые инструменты проверки могут жаловаться на смешение/несоответствие отступов (например, пробелы в этом блоке, вкладки для кода - если один предпочитает вкладки, конечно)
Есть ли какие-либо рекомендации по этому вопросу?