为 Perl 编写 POD 注释是否有任何约定？答案

【问题标题】：Are there any conventions for writing POD comments for Perl?为 Perl 编写 POD 注释是否有任何约定？
【发布时间】：2010-12-03 23:16:12
【问题描述】：

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

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

【问题讨论】：

【解决方案1】：

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

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

【讨论】：

【解决方案2】：

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

【讨论】：

您知道这些是否可以在线免费获得？我喜欢这本书的建议（特别是因为它看起来非常完整和深入），但最好是免费提供一些让我入门的东西。
@Thomas Owens：我认为没有任何书籍内容可以在线免费获得。 Sinan 与 Perl::Critic 的链接很好。另一种选择是查看一些核心 CPAN 模块的文档。虽然方法可能会有所不同，但有一些标准部分等作为指南很有帮助。

【解决方案3】：

Perl::Critic 提供以下政策：

A list of required sections 由上述最后一条策略提供。

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

【讨论】：

“写作提示”与内容无关。我可能应该将我的问题编辑得更清楚，但我专门寻找内容和设计（切片、标题、缩进......）约定。我正在查看 RequirePodSections 来修改我查看的模板以尝试改进它。
是的，为 RequirePodSections 文档的默认必需部分部分 +1。我正在使用它来修改我链接到的原始模板。我认为我有一些不错的东西，比我开始的要好。

【解决方案4】：

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

这与您将获得的指南非常接近。

【讨论】：