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.
POD can also be used in-line with code but I prefer to put at bottom of program after __END__ (as recommended by Damian Conway in Perl Best Practices).
Not to be overly flip, but the best way to document Perl code is the same way as you would document code in any other language.
As for specific tools, I use a mix of standard inline comments, pod for larger chunks of documentation where a format similar to man is appropriate, and TeX as a final fallback for documents that need to be more freeform. (And, in the spirit of "same as any other language", yes, I do use pod for documenting non-Perl code as well.)
Check out Pod::ProjectDocs - you get a simple command-line utility that will convert all the POD in your Perl project into a set of HTML pages that look just like what you see on search.cpan.org.
seperate user docs and coders docs. maybe put user docs (tuts, faq, reference) in there directory (/doc) and coders in same as the code. unfortunately its expected by conventtion, to have overview in the module itself. this you can as already layed out do it POD after END. mane coding docs you can put in comments. additional things like coding style or how to contribute put in seperate .pod files inside the code base (root dir?)
发布评论
评论（8）
查看几乎所有 Perl 模块的内部，您都会看到普通旧文档 (POD) 格式。 在 CPAN 搜索 上，查看模块时，您可以选择查看原始源代码，因此这是您可以查看原始 pod，但您也可以从命令行使用 perldoc 。
-m开关向您显示该文件，或者，如果您想查找该文件以便可以在您喜欢的编辑器中查看它，请使用
-l开关来查找它：一旦开始记录程序，您就可以将 Pod 与代码一起放入文件中，或者与代码交织在一起，以便文档位于相关部分旁边，或者作为一大块放在开头、中间或结尾。
使用 Perl 附带的翻译器（pod2latex、pod2ps、pod2html）可以轻松将 Pod 翻译为其他几种格式，例如 LaTeX、Postscript、HTML 等。 我什至有一个可用于 InDesign 的 pod 翻译器。 使用 Pod::Simple 可以轻松编写自己的 Pod 翻译器，所以如果您不这样做找到一个翻译成你最喜欢的最终形式，你自己做就可以了。
您还可以将一些工具添加到测试套件中来检查您的 Pod。 Test::Pod 模块检查格式错误，Test::Pod::Coverage 模块检查您记录的每个子例程，等等。 您可能还对我的 Perl 文档感兴趣。
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
-mswitch shows you the fileOr, if you want to find the file so you can look at it in your favorite editor, use the
-lswitch to find it: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.
我绝对推荐 POD。
POD 也可以与代码一起使用，但我更喜欢放在 __END__ 之后的程序底部（如 Damian Conway 在 Perl 最佳实践）。
查看 POD::Server & POD::Webserver，提供 Web 前端-结束您的所有 POD。
I definitely recommend POD.
POD can also be used in-line with code but I prefer to put at bottom of program after __END__ (as recommended by Damian Conway in Perl Best Practices).
Look at POD::Server & POD::Webserver, which provides a web front-end to all your PODs.
Perl pod。
这就是 Mozilla 记录 Perl 的方式。
Perl pod.
This is how Mozilla documents their Perl.
不要过度翻转，但记录 Perl 代码的最佳方式与记录任何其他语言的代码的方式相同。
至于特定工具，我混合使用标准内联注释、用于较大块文档的 pod（其中类似于 man 的格式是合适的），以及 TeX 作为需要更自由格式的文档的最终后备。 （并且，本着“与任何其他语言相同”的精神，是的，我也使用 pod 来记录非 Perl 代码。）
Not to be overly flip, but the best way to document Perl code is the same way as you would document code in any other language.
As for specific tools, I use a mix of standard inline comments, pod for larger chunks of documentation where a format similar to man is appropriate, and TeX as a final fallback for documents that need to be more freeform. (And, in the spirit of "same as any other language", yes, I do use pod for documenting non-Perl code as well.)
查看 Pod::ProjectDocs - 您将获得一个简单的命令行实用程序，可以将将 Perl 项目中的所有 POD 转换为一组 HTML 页面，这些页面看起来就像您在 search.cpan.org。
Check out Pod::ProjectDocs - you get a simple command-line utility that will convert all the POD in your Perl project into a set of HTML pages that look just like what you see on search.cpan.org.
没有人提到Smart::Comments？ 这并不总是您想要的，但如果您需要更多的评论权力，那就太好了。
No one mentioned Smart::Comments? It's not always what you want but good if you need more power to comments.
您可能还想查看 Damian Conway 撰写的 Perl 最佳实践。 我使用了一些技巧来清理我继承的一个小型 Perl 代码库。
You might also want to check out Perl Best Practices by Damian Conway. I used some of the tips to clean up a small Perl code base I inherited.
单独的用户文档和编码器文档。 也许将用户文档（tuts、faq、reference）放在目录（/doc）中，并将编码器放在与代码相同的目录中。 不幸的是，按照惯例，我们期望在模块本身中有概述。 正如已经安排好的，您可以在END之后执行POD。 您可以在评论中添加鬃毛编码文档。 其他的东西，比如编码风格或如何贡献放入代码库（根目录？）内的单独 .pod 文件中
seperate user docs and coders docs. maybe put user docs (tuts, faq, reference) in there directory (/doc) and coders in same as the code. unfortunately its expected by conventtion, to have overview in the module itself. this you can as already layed out do it POD after END. mane coding docs you can put in comments. additional things like coding style or how to contribute put in seperate .pod files inside the code base (root dir?)