perl - 为 Perl 编写 POD 注释是否有任何约定？

Question

我能够从 Safari Books Online 中找到一个提供模板的页面，但是我从未写过 POD 评论，我不确定它有多好，或者它是否缺少任何可能被视为包含约定的内容。

为 Perl 脚本编写 POD 注释时要遵循哪些约定？有没有像Sun 的 Javadoc Conventions一样的东西，但对于 POD 注释？

Answer 1

Perl 最佳实践中有一组建议。整个第 7 章涵盖了文档、使用 POD，以及为模块、大型项目等编写文档的最佳方法。它还讨论了 CPAN 约定。这可能是你最好的选择。

Answer 2

它并不详尽，但我非常喜欢 Juerd 的perlpodtut介绍。

作者提到了他认为常见的部分以及它们将包括的内容。

Answer 3

Perl::Critic提供以下策略：

• Perl::Critic::Policy::Documentation::PodSpelling

• Perl::Critic::Policy::Documentation::RequirePackageMatchesPodName

• Perl::Critic::Policy::Documentation::RequirePodAtEnd

• Perl::Critic::Policy::Documentation::RequirePodSections

上述最后一项政策提供了所需部分的列表。

Module::Starter::PBP将为您生成样板代码。

Answer 4

您可以在CPAN Search上查看 Perl 模块的 Pod，并快速记下每个人所做的事情。各种模块启动工具为您制作样板。

这与您将获得的指导方针一样接近。