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.
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.
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
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
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.
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!
In retrospect (2.5 years later), Docco may have done exactly what I was looking for: http://jashkenas.github.com/docco/
What about Doxygen? It is a software documentation tool, originally written for C/C++. It is pretty similar to JavaDoc, but it supports multiple programming languages (e.g. C/C++, C#, Objective-C, Java, Python, PHP, ecc..).
There is also a Perl-based version: Doxygen::Filter::Perl
Here you can find all the documentation: http://www.stack.nl/~dimitri/doxygen/manual/commands.html
I personally found it much more useful than POD, especially because one can immediately see (also from the code) what a method or function will take as a parameter and/or what it will return.
I like Doxygen. Doxygen Filter allows you to use Doxygen style comments for documenting Perl code, which like JavaDoc. doxygen