Существуют ли соглашения для написания комментариев к POD для Perl?

Question

Мне удалось найти страницу из Safari Books Online, в которой есть шаблон , но я так и не написал комментарии POD, но я не уверен, насколько он хорош, или он пропускает что-то, что может считается конвенцией включать.

Какие соглашения следует соблюдать при написании комментариев POD для сценариев Perl? Есть ли что-то вроде соглашений Javadoc Sun , кроме комментариев POD?

Answer 1

Это не сложно, но мне очень нравится введение Джерда perlpodtut .

Автор упоминает, что он считает общими разделами и что они будут включать.

Answer 2

В Perl Best Practices есть ряд рекомендаций. Вся глава 7 охватывает документацию, использование POD и лучшие подходы к документации для модулей, крупных проектов и т. Д. В нем также говорится о соглашениях CPAN. Это, вероятно, ваш лучший выбор.

Answer 3

Perl :: Critic предоставляет следующие политики:

• Perl :: Критик :: Политика :: Документация :: PodSpelling

• Perl :: Критик :: Политика :: Документация :: RequirePackageMatchesPodName

• Perl :: Критик :: Политика :: Документация :: RequirePodAtEnd

• Perl :: Критик :: Политика :: Документация :: RequirePodSections

Список обязательных разделов предоставляется последней политикой выше.

Модуль :: Стартер :: PBP сгенерирует стандартный код для вас.

Answer 4

Вы можете посмотреть на Pod для модулей Perl в CPAN Search и быстро заметить, что все делают. Различные стартовые инструменты для модулей делают шаблон для вас.

Это примерно так же близко, как вы получите к руководящим принципам.