27

有什么建议可以记录我的 Perl 代码吗？您使用什么以及可以使用哪些工具来帮助我？

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

4

8 回答 8

48

查看几乎所有 Perl 模块，您会看到普通旧文档 (POD)格式。在CPAN Search上，查看模块时，您可以选择查看原始源代码，这是查看原始 pod 的一种方式，但您也可以从命令行使用perldoc 。-m开关显示文件

perldoc -m Foo::Bar

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

perldoc -l Foo::Bar

一旦你开始记录你的程序，你将 Pod 与代码一起放入文件中，要么与代码交织在一起，因此文档就在相关部分的旁边，或者在开头、中间或结尾处作为一大块。

Pod 可以通过 Perl 附带的翻译器（pod2latex、pod2ps、pod2html）轻松翻译成其他几种格式，例如 LaTeX、Postscript、HTML 等。我什至有一个用于 InDesign 的 pod 翻译器。使用Pod::Simple编写自己的 Pod 翻译器很容易，所以如果你没有找到你最喜欢的最终形式的翻译器，那就自己做吧。

您还可以将几个工具添加到您的测试套件中以检查您的 Pod。Test::Pod模块检查格式错误，Test ::Pod::Coverage模块检查您记录的每个子例程，等等。您也可能对我的Perl 文档文档感兴趣。

于 2008-10-10T11:29:35.077 回答
25

我绝对推荐POD。

POD 也可以与代码一起使用，但我更喜欢在 __END__ 之后放在程序的底部（正如 Damian Conway 在Perl Best Practices中推荐的那样）。

查看POD::Server和 POD::Webserver，它为所有 POD 提供了 Web 前端。

于 2008-10-10T11:43:56.923 回答
21

Perl 吊舱。

这就是 Mozilla 记录他们的 Perl 的方式。

于 2008-10-10T10:43:24.623 回答
10

不要过度翻转，但是记录 Perl 代码的最佳方式与记录任何其他语言的代码的方式相同。

至于具体的工具，我混合使用标准的内联注释，使用类似于man格式的较大文档块的 pod以及需要更自由格式的文档作为最终后备的 TeX。（而且，本着“与任何其他语言相同”的精神，是的，我也使用 pod 来记录非 Perl 代码。）

于 2008-10-10T11:28:48.183 回答
6

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

查看Pod::ProjectDocs - 您将获得一个简单的命令行实用程序，它将把 Perl 项目中的所有 POD 转换为一组 HTML 页面，看起来就像您在search.cpan.org上看到的一样。

于 2008-10-17T18:39:35.660 回答
4

没有人提到Smart::Comments？如果您需要更多的评论权力，这并不总是您想要的，但很好。

于 2008-12-25T19:46:22.873 回答
3

您可能还想查看Damian Conway 的Perl Best Practices。我使用了一些技巧来清理我继承的一个小型 Perl 代码库。

于 2008-10-21T16:02:44.323 回答
3

单独的用户文档和编码器文档。可能将用户文档（tuts，faq，reference）放在目录（/doc）中，编码器与代码相同。不幸的是，它被约定所期望，对模块本身有概述。这个你可以在END之后做 POD 。您可以在评论中添加鬃毛编码文档。其他内容，例如编码风格或如何贡献代码库（根目录？）中的单独 .pod 文件

于 2011-11-12T17:30:42.463 回答