Какой лучший способ документировать код Perl?

Ответ 1

Просмотрите почти любой модуль Perl, и вы увидите формат CPAN Search при просмотре модуля вы можете просмотреть исходный источник, так что в одном случае вы можете посмотреть на необработанный блок, но вы также можете использовать perldoc из командной строки. Переключатель -m показывает файл

perldoc -m Foo::Bar

Или, если вы хотите найти файл, чтобы просмотреть его в своем любимом редакторе, используйте переключатель -l, чтобы найти его:

perldoc -l Foo::Bar

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

Pod легко переводится в несколько других форматов, таких как LaTeX, Postscript, HTML и т.д. с переводчиками, которые поставляются с Perl (pod2latex, pod2ps, pod2html). У меня даже есть переводчик, который идет в InDesign. Написание собственного переводчика Pod легко с Pod:: Simple, поэтому, если вы не найдете переводчика в свою любимую окончательную форму, просто сделайте это сами.

Есть также несколько инструментов, которые вы можете добавить в свой тестовый набор, чтобы проверить свой Pod. Модуль Test:: Pod проверяет ошибки формата, Test:: Pod:: Coverage проверяет, что вы задокументировали каждую подпрограмму, и так далее. Вы также можете быть заинтересованы в моей документации документации Perl.

Ответ 2

Я определенно рекомендую POD.

POD также можно использовать в строке с кодом, но я предпочитаю помещать внизу программы после __END__ (как рекомендовал Дамиан Конвей в Perl Best Practices).

Посмотрите POD:: Server и POD:: Webserver, который предоставляет веб-интерфейс всем вашим POD.

Ответ 3

Perl pod.

Так Mozilla документирует свой Perl.

Ответ 4

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

Что касается конкретных инструментов, я использую сочетание стандартных встроенных комментариев, pod для более крупных фрагментов документации, где подходит формат, похожий на man, а TeX как окончательный резерв для документов, которые необходимо быть более свободной формой. (И, в духе "так же, как любой другой язык", да, я использую pod для документирования не Perl-кода.)

Ответ 5

Какой модуль вы используете для конвертации pod в html?

Отъезд Pod:: ProjectDocs - вы получаете простую утилиту командной строки, которая преобразует все POD в ваш проект Perl в набор HTML-страниц, которые выглядят так же, как вы видите на search.cpan.org.

Ответ 6

Вы также можете проверить Perl Best Practices от Damian Conway. Я использовал некоторые советы, чтобы очистить небольшую базу кода Perl, которую я унаследовал.

Ответ 7

Никто не упоминал Smart:: Comments? Это не всегда то, что вы хотите, но хорошо, если вам нужно больше энергии для комментариев.

Ответ 8

отдельные документы для документов и кодеров. возможно, поставить пользовательские документы (tuts, faq, reference) в каталог (/doc) и кодеры, такие же, как и код. к сожалению, ожидается, что он будет представлен в самом модуле. это вы можете, как уже выложено, сделать это POD после END. mane coding docs вы можете добавлять комментарии. дополнительные вещи, такие как стиль кодирования или как внести вклад в отдельные файлы .pod внутри базы кода (root dir?)