perlpodstyle - Интернет в облаке

ПРОГРАММА:

ИМЯ

perlpodstyle - руководство по стилю Perl POD

ОПИСАНИЕ

Это общие рекомендации по написанию документации POD для сценариев Perl и
модули, основанные на общих рекомендациях по написанию хороших страниц руководства UNIX. Все из этого
рекомендации, конечно, необязательны, но следование им сделает вашу документацию более
в соответствии с другой документацией по системе.

Название документируемой программы обычно выделяется жирным шрифтом (с использованием B <>).
где бы это ни происходило, как и все параметры программы. Аргументы пишутся курсивом.
(Я <>). Названия функций традиционно пишутся курсивом; если вы напишете функцию как
функция (), Pod :: Человек позаботится об этом за вас. Буквальный код или команды должны быть
в C <>. Ссылки на другие справочные страницы должны быть в форме «справочная страница (раздел)» или
"L ", и Pod :: Man автоматически отформатирует их соответствующим образом.
вторая форма, с L <>, используется для запроса, чтобы модуль форматирования POD сделал ссылку на страницу руководства.
если возможно. В качестве исключения обычно пропускают раздел при ссылке на модуль
документация, так как непонятно, в каком разделе будет документация модуля; использовать
"L "вместо ссылок на модули.

Ссылки на другие программы или функции обычно представлены в виде ссылок на страницы руководства.
так что инструменты перекрестных ссылок могут предоставлять пользователю ссылки и тому подобное. Это
можно переборщить, поэтому будьте осторожны, чтобы не загромождать документацию
много наценки. Ссылки на другие программы, не указанные в справочных страницах.
должны быть заключены в B <>.

Основные заголовки должны быть указаны с помощью директивы "= head1" и исторически
написано в довольно поразительном формате ALL UPPER CASE; это не обязательно, но это
настоятельно рекомендуется, чтобы разделы имели единообразные названия в разных программах.
пакеты. Незначительные заголовки могут быть включены с помощью "= head2" и обычно используются в смешанном регистре.

Стандартные разделы справочной страницы:

ИМЯ
Обязательный раздел; должен быть список программ или функций, разделенных запятыми.
задокументировано на этой странице POD, например:

foo, bar - программы, которые что-то делают

Индексаторы страниц вручную часто очень придирчивы к формату этого раздела, поэтому
не помещайте в него ничего, кроме этой строки. Каждая программа или функция, задокументированная
эта страница POD должна быть указана через запятую и пробел. Для модуля Perl,
просто укажите имя модуля. Одиночное тире и только одно тире должно разделять
список программ или функций из описания. Не используйте разметку типа C <>
или B <> в любом месте этой строки. Функции не должны быть обозначены знаком "()" или
нравиться. Описание должно идеально умещаться в одной строке, даже если программа man
заменяет тире несколькими вкладками.

СИНТАКСИС
Краткое описание использования программ и функций. Этот раздел обязателен для
раздел 3 страницы. Для документации модуля Perl обычно удобно иметь
содержание этого раздела представляет собой дословный блок, показывающий некоторые (краткие) примеры типичных
способы использования модуля.

ОПИСАНИЕ
Расширенное описание и обсуждение программы или функций, или тела
документация для страниц руководства, которые документируют что-то еще. Если особенно долго, это
Хорошая идея разбить это на подразделы директив "= head2", например:

= head2 Нормальное использование

= head2 Расширенные возможности

= head2 Запись файлов конфигурации

или все, что подходит для вашей документации.

Для модуля это обычно то место, где документация интерфейсов, предоставляемая
модуль идет, как правило, в виде списка с "= item" для каждого интерфейса.
В зависимости от количества интерфейсов вы можете поместить эту документацию в
вместо этого разделите разделы МЕТОДЫ, ФУНКЦИИ, МЕТОДЫ КЛАССА или МЕТОДЫ ЭКЗАМЕНА и
сохраните раздел ОПИСАНИЕ для обзора.

ДОПОЛНИТЕЛЬНЫЕ УСЛУГИ, НЕ ВКЛЮЧЕННЫЕ В ПАКЕТ
Подробное описание каждой из опций командной строки, используемых программой. Этот
должно быть отдельно от описания использования парсеров, таких как Pod :: Usage. Этот
обычно представлен в виде списка, с каждым параметром как отдельный "= элемент". Конкретные
Строка опции должна быть заключена в B <>. Любые значения, которые принимает параметр, должны быть
заключено в I <>. Например, раздел для опции --раздел=манекст был бы
представлен с:

= элемент B <--section> = I

Синонимические параметры (как краткая, так и полная форма) разделяются запятой и
пробел в той же строке "= item" или, необязательно, указан как отдельный элемент с
ссылка на каноническое имя. Например, поскольку --раздел также может быть написано как
-s, приведенное выше будет:

= элемент B <-s> I , B <--section> = I

Рекомендуется сначала написать краткий вариант, потому что его легче читать. Долго
вариант достаточно длинный, чтобы в любом случае привлечь внимание, а короткий вариант в противном случае может
потеряться в визуальном шуме.

ВОЗВРАТНАЯ СТОИМОСТЬ
Что возвращает программа или функция в случае успеха. Этот раздел можно опустить для
программы, точные коды выхода которых не важны, при условии, что они возвращают 0 в случае успеха
и ненулевое значение при отказе, как это обычно бывает. Он всегда должен присутствовать для функций.
Для модулей может быть полезно суммировать возвращаемые значения из интерфейса модуля.
здесь, или может быть более полезно обсудить возвращаемые значения отдельно в
документация по каждой функции или методу, которые предоставляет модуль.

ОШИБКИ
Исключения, коды возврата ошибок, статусы выхода и настройки ошибок. Обычно используется для
документация по функциям или модулям; в программной документации используется ДИАГНОСТИКА. В
общее эмпирическое правило заключается в том, что ошибки выводятся в "STDOUT" или "STDERR" и предназначены для
конечный пользователь задокументирован в ДИАГНОСТИКЕ, в то время как ошибки передаются внутри вызывающей
Программа, предназначенная для других программистов, задокументирована в ОШИБКИ. При документировании
функция, которая устанавливает errno, должен быть дан полный список возможных значений errno
здесь.

ДИАГНОСТИКИ
Все возможные сообщения, которые программа может распечатать, и их значение. Вы можете пожелать
следовать тому же стилю документации, что и документация Perl; видеть Perldiag(1) для
подробнее (а также посмотрите исходный код POD).

Если возможно, укажите подробные сведения о том, что должен сделать пользователь, чтобы исправить ошибку;
документируют ошибку как указание на то, что "входной буфер слишком мал", не сообщая
пользователь, как увеличить размер входного буфера (или, по крайней мере, сказать им, что он
невозможно) не очень полезны.

ПРИМЕРЫ
Приведите несколько примеров использования программы или функции. Не экономьте; пользователи часто находят это
самая полезная часть документации. Примеры обычно даются как
дословные абзацы.

Не просто приводите пример, не объясняя, что он делает. Добавление короткого
абзац, в котором говорится, что будет делать пример, может увеличить ценность примера
безмерно.

ОКРУЖАЮЩАЯ СРЕДА
Переменные среды, которые важны для программы, обычно представлены в виде списка с использованием
«= поверх», «= элемент» и «= назад». Например:

= более 6

= элемент HOME

Используется для определения домашнего каталога пользователя. F <.foorc> в этом
Каталог читается для получения сведений о конфигурации, если он существует.

= назад

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

FILES
Все файлы, используемые программой или функцией, обычно представляемые в виде списка, и что это
использует их для. Имена файлов должны быть заключены в F <>. Особенно важно
файлы документов, которые могут быть потенциально изменены.

Пещеры
Вещи, о которых нужно проявлять особую осторожность, иногда называемые ПРЕДУПРЕЖДЕНИЯМИ.

ОШИБКИ
Вещи, которые сломаны или просто не работают, как следует.

ОГРАНИЧЕНИЯ
Ошибки, которые вы не планируете исправлять. :-)

ПРИМЕЧАНИЯ
Разные комментарии.

АВТОР
Кто это написал (используйте АВТОРЫ для нескольких человек). Хорошая идея - включить
текущий адрес электронной почты (или какой-либо адрес электронной почты, на который следует отправлять отчеты об ошибках) или
некоторая другая контактная информация, чтобы пользователи могли связаться с вами. Помнить
эта программная документация имеет тенденцию бродить по дикой природе гораздо дольше, чем вы ожидаете, и
выберите способ связи, который, вероятно, продлится долго.

ИСТОРИЯ
Программы, полученные из других источников, иногда имеют это. Некоторые люди держат
журнал изменений здесь, но он обычно становится длинным и обычно лучше поддерживается в
отдельный файл.

АВТОРСКИЕ ПРАВА И ЛИЦЕНЗИЯ
За авторское право

Авторские права ГОД (-а) ВАШЕ ИМЯ (-Я)

(Нет, (C) не требуется. Нет, «Все права защищены» не требуется.)

Для лицензирования проще всего использовать то же лицензирование, что и сам Perl:

Эта библиотека является бесплатным программным обеспечением; вы можете распространять его и / или
измените его на тех же условиях, что и сам Perl.

Это упрощает использование вашего модуля с Perl. Обратите внимание, что это лицензирование
пример не является ни одобрением, ни требованием, вы, конечно, можете выбирать
любое лицензирование.

СМОТРИТЕ ТАКЖЕ
Другие справочные страницы для ознакомления, например человек(1) человек(7) приготовить(8) или Catman(8).
Обычно простой список страниц руководства, разделенных запятыми, или абзац с указанием
название справочной работы. Ссылки на страницы руководства, если они используют стандартную
форма "имя (раздел)" не обязательно заключать в L <> (хотя это рекомендуется),
но другие вещи в этом разделе, вероятно, должны быть при необходимости.

Если в пакете есть список рассылки, укажите здесь URL-адрес или инструкции по подписке.

Если в пакете есть веб-сайт, укажите здесь URL-адрес.

В документации по объектно-ориентированным библиотекам или модулям может потребоваться использование КОНСТРУКТОРОВ и
Разделы МЕТОДЫ или разделы МЕТОДЫ КЛАССА и МЕТОДЫ ЭКСПЕРИМЕНТА
документацию по частям библиотеки и сохраните раздел ОПИСАНИЕ для
обзор. Большие модули с функциональным интерфейсом могут захотеть использовать ФУНКЦИИ для аналогичных
причины. Некоторые люди используют ОБЗОР, чтобы резюмировать описание, если оно довольно длинное.

Порядок разделов варьируется, хотя ИМЯ всегда должно быть первым разделом (вы нарушите некоторые
в других случаях системы страниц руководства), а ИМЯ, ОБЗОР, ОПИСАНИЕ и ПАРАМЕТРЫ обычно всегда
появляются первыми и в том же порядке, если они есть. В общем, СМОТРИ ТАКЖЕ, АВТОРА и т.п.
материал следует оставить напоследок. Некоторые системы также переносят ПРЕДУПРЕЖДЕНИЯ и ЗАМЕТКИ на последний срок. В
Приведенный выше порядок должен быть разумным для большинства целей.

Некоторые системы используют CONFORMING TO для обозначения соответствия соответствующим стандартам, а MT-LEVEL - для обозначения соответствия требованиям.
обратите внимание на безопасность использования в многопоточных программах или обработчиках сигналов. Эти заголовки
в первую очередь полезно при документировании частей библиотеки C.

Наконец, в качестве общего замечания постарайтесь не использовать чрезмерное количество разметки. Как задокументировано
здесь и в Pod :: Man вы можете спокойно оставить Perl-переменные, имена функций, справочную страницу
ссылки и тому подобное, без разметки, и переводчики POD разберутся в этом
для тебя. Это значительно упрощает последующее редактирование документации. Обратите внимание, что многие
существующие переводчики будут делать неправильные вещи с адресами электронной почты, если они заключены в L <>, поэтому
не делай этого

Используйте perlpodstyle онлайн с помощью сервисов onworks.net