How can I generate HTML documentation for Perl code comments?

Question

I've come into ownership of a bunch of code that's held together with various Perl scripts. There's some documentation in the form of comments (not Pod) embedded in these scripts that I'd like to be able to extract and browse in an HTML format.

Basically, I'm looking for something like javadoc or rubydoc, but for Perl. "perldoc" seemed like an obvious search string, but I guess that's just the documentation for Perl itself. "perlpod" also came up, but I'm looking for something that extracts comments that already exist in the code without much special formatting. (Having to add extra bits would seem to be counterproductive.)

Whatever tool I choose, I'd like to point it to the code and have it recursively find Perl files, generate documentation, and save it in a directory that I choose. It should also be cross-platform (Windows XP, 7, Mac OS X, and Ubuntu Linux). Something written in Perl itself would seem to qualify. It also should play nicely with other programming languages, if possible.

What are some options you'd recommend?

Sorry for my ignorance -- I've never done much beyond simple stuff with Perl before.

Answer 1

Natural Docs is written in Perl and can document a number of languages. It's pretty flexible in terms of what it can document. I'm pretty sure it can do everything you've asked for here. Give it a look!

Answer 2

Look more into perldoc. It is a tool for viewing and generating module documentation as well as a command-line tool for reading the Perl documentation.

For example, you can create an HTML file of a module's pod with

perldoc -o html path/to/Module.pm

Answer 3

If your Perl files contain Perl's Plain Old Documentation (POD), you can use pod2html to generate HTML.

Or, maybe you can adapt this to suit your needs: Comments to POD - com2pod.pl

Answer 4

Documentation in comments? These are two different concepts. Comments are for the maintenance programmer, documentation is for the user.

How very unlazy. What will the unvirtuous newbies think of next? °_°;

Convert the text from comment form to POD, meaning removing the # characters and tacking some appropriate =command paragraphs above and below. Then you can employ the whole POD toolchain for checking, converting etc.

Answer 5

I do not have any experience with it, but Pod::Autopod looks interesting. It comes with a command line utility autopod.

autopod - using the Perl library Pod::Autopod to generate javadoc like documentation with pod syntax. It is designed to understand perl code in class style, so typically PM files.

It might be worth a look. Please let us know if you do try it out.