logo标签列表

记录Perl代码的最佳方式是什么？

perldocumentationperl-pod
27

你有什么建议可以文档化你的Perl代码？你使用什么工具来帮助你，有哪些可用的工具？

你使用哪个模块将pod转换为html？

关于口味问题，我个人更喜欢 Doxygen（Doxygen::Filter::Perl）而不是 POD。 - Paolo Rovelli
8个回答
48

几乎所有的Perl模块内部都包含Plain Old Documentation (POD)格式。在CPAN Search上查看模块时，您可以选择查看原始源代码，这是一种查看原始POD的方法，但您也可以使用命令行上的perldoc。使用-m开关可显示文件。

perldoc -m Foo::Bar

或者，如果您想找到文件以便在您喜欢的编辑器中查看它，请使用-l开关进行查找：

perldoc -l Foo::Bar

一旦开始记录程序，您就可以将Pod放在与代码一起的文件中，可以将其与代码交织在一起，使文档与相关部分相邻，或者作为一个大块出现在开头、中间或末尾。

Pod可以很容易地转换为其他格式，例如LaTeX、Postscript、HTML等，使用随Perl附带的翻译器（pod2latex、pod2ps、pod2html）进行转换。我甚至有一个pod翻译器可以转换为InDesign。使用Pod::Simple编写自己的Pod翻译器非常容易，因此，如果没有找到转换为所需格式的翻译器，只需自己制作即可。

还有一些工具可以添加到测试套件中以检查您的Pod。 Test::Pod模块检查格式错误，Test::Pod::Coverage模块检查是否已经记录了每个子例程，等等。 您可能还会对我的Perl文档文档感兴趣。

25

我强烈推荐使用POD。

POD也可以与代码内联使用，但我更喜欢将其放在程序的底部，在 __END__ 后面（如 Damian Conway 在 Perl 最佳实践 中建议的那样）。

看看POD::Server和POD::Webserver，它们提供了一个 Web 前端，用于访问你所有的 PODs。

21

Perl pod是一种用于文档编写的标记语言，常用于Perl程序中。

这是Mozilla记录其Perl代码的方式。

10

不要过于轻率，但是记录Perl代码的最佳方式与记录其他语言的代码相同。

至于具体工具，我使用标准的行内注释、对于较大块的文档使用类似于man的格式的pod，并在需要更自由形式的文档中使用TeX作为最终备选方案。(而且，遵循“与任何其他语言相同”的精神，我确实也使用pod来记录非Perl代码。)

6
您使用哪个模块将pod转换为html？
请查看Pod::ProjectDocs - 您将获得一个简单的命令行实用程序，它将把您Perl项目中的所有POD转换为一组HTML页面，这些页面看起来就像search.cpan.org上看到的那样。
现在，在某些情况下，使用Mojolicious::Plugin::PODRenderer是非常方便的。 - Eugen Konkov
4
没有人提到Smart::Comments吗？它不总是你想要的，但如果你需要更强大的注释功能，它很好用。
这个模块太棒了。有点惊讶以前从未听说过它。我写子程序来实现这个模块能提供的部分功能，不知道有多少次了。强烈推荐使用。 - slm
3

您可能还想查看Damian Conway所著的Perl最佳实践。我使用了其中一些技巧来清理我继承的一个小型Perl代码库。

3

将用户文档和编码者文档分开。可以将用户文档（教程，常见问题解答，参考资料）放在其目录（/doc）下，将编码者文档放在与代码相同的位置。不幸的是，按照约定，模块本身必须有概述。您可以像之前所述那样，在END之后使用POD来实现此操作。您可以将许多编码文档放在注释中。将其他内容（例如编码风格或如何贡献）放在代码库（根目录？）中的单独.pod文件中。

网页内容由stack overflow 提供, 点击上面的
可以查看英文原文，
原文链接