记录Perl代码的最好方式是什么？ [英] What's the best way to document Perl code?

问题描述

任何建议如何记录我的Perl代码？您使用什么工具和可用的工具来帮助我？

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

解决方案

查看几乎任何Perl模块，你会看到普通旧文档（POD）格式。在 CPAN搜索中，当查看模块时，您可以选择查看原始来源，这样就可以查看原始pod，但您也可以在命令行中使用 perldoc 。 -m 开关显示文件

  perldoc -m Foo： ：Bar 
  

或者，如果你想找到文件，你可以在你最喜爱的编辑器中查看，请使用 -l <​​/ code>开关找到它：

  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文档文档感兴趣。

Any suggestion how I can document my Perl code? What do you use and what tools are available to help me?

Which module do you use to convert pod to html?

解决方案

Look inside almost any Perl module and you'll see the Plain Old Documentation (POD) format. On CPAN Search, when looking at a module you have the option of viewing the raw source, so that's one way you can look at the raw pod, but you can also use perldoc from the command line. The -m switch shows you the file

perldoc -m Foo::Bar

Or, if you want to find the file so you can look at it in your favorite editor, use the -l switch to find it:

perldoc -l Foo::Bar

Once you start documenting your program, you put the Pod in the file right with the code, either interwoven with the code so the documentation is next to the relevant parts, or at the beginning, middle, or end as one big chunk.

Pod is easily translated to several other formats, such as LaTeX, Postscript, HTML, and so on with translators that come with Perl (pod2latex, pod2ps, pod2html). I even have a pod translator that goes to InDesign. Writing your own Pod translator is easy with Pod::Simple, so if you don't find a translator to your favorite final form, just make it yourself.

There are also several tools that you can add to your test suite to check your Pod. The Test::Pod module checks for format errors, the Test::Pod::Coverage module checks the you've documented each subroutine, and so on. You also might be interested in my Perl documentation documentation.

这篇关于记录Perl代码的最好方式是什么？的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！