Правильный способ документирования параметров переменной длины на страницах руководства

Правильный способ документирования параметров переменной длины на страницах руководства

Иногда я вижу такую ​​информацию об использовании:

some_utility [arg [arg [...]]]

или

some_utility [arg[, arg[...]]]

это означает, что вы можете передать более одного одного и того же аргумента.

Я также видел это как

some_utility [args]

или

some_utility [arg][, arg][...]

Есть ли стандартный способ сделать это?

решение1

Нет, нет.Действительно, но в большинстве случаев это довольно последовательно. Большинство руководств перечисляют необязательные аргументы в квадратных скобках ( [foo]), обязательные — в угловых скобках или вообще без скобок ( <bar>, baz, последний часто подчеркивается).

Кроме того, почти во всех случаях, если число аргументов является переменным, у вас будет некий список (как вы упомянули, [quux ...]или [quux[, quux[...]]]...), где аналогично [quuz]в большинстве случаев обозначается именноодинаргумент. В редких случаях [quuz]может также означать »один или несколько аргументов«, но большинство руководств придерживаются многоточия в форме перечисления.

Это квазистандарт, но на него нельзя положиться. Но по моему опыту, в 95% случаев это нормально.

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

Связанный контент