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

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

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

查看几乎所有Perl模块,您将看到Plain Old Documentation(POD)格式.在CPAN搜索中,当查看模块时,您可以选择查看原始源,这样您可以通过一种方式查看原始窗格,但也可以从命令行使用perldoc.该-m开关显示您的文件

perldoc -m Foo::Bar

或者,如果要查找文件以便在您喜欢的编辑器中查看它,请使用-l开关查找它:

perldoc -l Foo::Bar

一旦开始记录程序,就可以使用代码将Pod放在文件中,或者与代码交织在一起,使文档位于相关部分旁边,或者在开头,中间或结尾处作为一个大块.

Pod可以很容易地翻译成其他几种格式,例如LaTeX,Postscript,HTML等,以及Perl附带的翻译器(pod2latex,pod2ps,pod2html).我甚至有一个转到InDesign的pod转换器.使用Pod :: Simple可以轻松编写自己的Pod转换器,因此如果您没有找到最喜欢的最终形式的翻译器,请自行制作.

您还可以添加几个工具添加到测试套件中以检查Pod.该测试::波德模块检查格式错误,测试::波德::覆盖模块检查你记录每个子程序,依此类推.您可能也对我的Perl文档文档感兴趣.

我绝对推荐POD.

POD也可以与代码一起使用,但我更喜欢在__END__之后放入程序的底部(根据Perl最佳实践中 Damian Conway的建议).

查看POD :: Server& POD :: Webserver,它为您的所有POD提供Web前端.

Perl pod.

这就是Mozilla如何记录他们的Perl.

不要过度翻转,但记录Perl代码的最佳方式与使用任何其他语言记录代码的方式相同.

至于具体的工具,我使用标准内联注释的混合,pod用于较大的文档块,其中类似于man的格式是合适的,而TeX则是需要更自由格式的文档的最终后备.(并且,本着"与任何其他语言相同"的精神,是的,我也使用pod来记录非Perl代码.)

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

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