Любое предложение, как я могу документировать свой код Perl? Что вы используете и какие инструменты доступны для меня?Каков наилучший способ документировать код Perl?
Какой модуль вы используете для преобразования pod в html?
Просмотрите почти любой модуль Perl, и вы увидите формат Plain Old Documentation (POD). На странице 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 documentation documentation.
Так Mozilla документирует свой Perl.
Не слишком перевернутый, но лучший способ документировать код Perl - это то же самое, что и код документа на любом другом языке.
Что касается конкретных инструментов я использую сочетание стандартных встроенных комментариев, стручка для больших кусков документации, когда формат похож на человека является подходящим, и TeX в качестве конечного запасного варианта для документов, которые должны быть более свободной формой. (И, в духе «так же, как любой другой язык», да, я использую pod для документирования кода без Perl.)
Я определенно рекомендую POD.
POD также может использоваться в соответствии с кодом, но я предпочитаю размещать внизу программы после __END__ (как рекомендовал Дамиан Конвей в Perl Best Practices).
Посмотрите на POD::Server & POD::Webserver, который предоставляет веб-интерфейс всем вашим POD.
Какой модуль вы используете для преобразования pod в html?
Заканчивать Pod::ProjectDocs - вы получите простую утилиту командной строки, которая будет конвертировать все POD в проекте Perl в набор HTML-страниц, которые выглядят так же, как то, что вы видите на search.cpan.org.
Теперь в некоторых случаях это доступно [Mojolicious :: Plugin :: PODRenderer] (http://mojolicious.org/perldoc/Mojolicious/Plugin/PODRenderer) –
Возможно, вы также захотите посмотреть Perl Best Practices от Damian Conway. Я использовал некоторые советы для очистки небольшой базы кода Perl, которую я унаследовал.
Никто не упоминается Smart::Comments? Это не всегда то, что вы хотите, но хорошо, если вам нужно больше возможностей для комментариев.
Этот модуль потрясающий. С удивлением я никогда не слышал об этом раньше. Не могу сказать, сколько раз я писал подпрограммы, чтобы делать части того, что может предложить этот модуль, не могу рекомендовать его достаточно. – slm
отдельные документы пользователя и документы для кодеров. возможно, поставить пользовательские документы (tuts, faq, reference) в каталог (/ doc) и кодеры, такие же, как и код. к сожалению, ожидается, что он будет представлен в самом модуле. это вы можете как уже выложено сделать это POD после END. mane coding docs вы можете добавлять комментарии. дополнительные вещи, такие как стиль кодирования или как внести вклад в отдельные файлы .pod внутри базы кода (корневой каталог?)
De gustibus. Я лично предпочитаю Doxygen (Doxygen :: Filter :: Perl) для POD. –