How can I generate HTML documentation for Perl code comments?

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.

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.

1 While it hardly does everything perfectly, it does exactly what I had in mind in terms of processing comments, generating the POD, and spitting out the HTML. – Benjamin Oakes Feb 10 '10 at 20:26.

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.

That's helpful to know, but this seems like a lot of work just to spit out what's already there in a slightly more readable fashion, even with com2pod. (It feels like I'm writing a documentation system myself. ) It seems hard to believe that this is the best option.Am I missing something?

– Benjamin Oakes Feb 10 '10 at 18:07 1 Does your Perl code contain POD? – toolic Feb 10 '10 at 18:14 No, the existing code (which I didn't write) just has comments about subroutines, etc.Above their definition. There are also descriptions about what the files are for before the code starts (e.g. , right after the shebang).

– Benjamin Oakes Feb 10 '10 at 18:16 2 I'd convert those comments to Pod first. Don't make a bad situation worst by making tools around a format you should be using. :) – brian d foy Feb 10 '10 at 23:19 1 Yeah, I try to act like a Roman when in Rome, but I'm also lazy/short on time.

Autopod seemed like a good compromise between using POD and not necessitating tons of menial formatting changes. – Benjamin Oakes Feb 10 '107 at 3:28.

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.

5 It is also the de facto standard for Perl code documentation (try browsing some code on CPAN). – reinierpost Feb 10 '10 at 17:10 That command you gave me didn't work (default installation of perl on OS X 10.6). – Benjamin Oakes Feb 10 '10 at 20:30 2 Can you say more about "didn't work"?

– brian d foy Feb 10 '10 at 23:17 Sorry, I should have been more specific. It was complaining about HTML not being a valid format. It turns out that I was specifying the wrong filename to process.

Your command actually does work. – Benjamin Oakes Feb 10 '10 at 3:26.

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.

1 Keeping the docs in the file next to the code, at least for libraries, means there is an easy way to tell some day that the docs don't match the code and no real excuse for letting the two diverge. Otherwise you are right that they are separate. – Paul Feb 10 '10 at 19:38 Since this is a question referring only to maintenance, the distinction seems irrelevant for this question.

– Benjamin Oakes Feb 10 '10 at 20:22 Paul: You totally misunderstood that, it's a seperation of meaning, not location. Benjamin: It's not irrelevant. Realise that comments and docs have different semantics and therefore are expressed in different syntax.

This is not an accident, as they are generally not exchangable. Making them so perverts the purpose. – daxim Feb 11 '10 at 13:56 I can appreciate that, but for the purposes of this question, I was only looking for a way to take what was already there and make it easy to browse.

– Benjamin Oakes Feb 11 '10 at 15:04.

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!

While I like the idea of Natural Docs (and it's default is prettier than pod2html) if you use some tool that is different from what every other Perl programmer uses you will have problems. – mpeters Feb 10 '10 at 18:23 1 @mpeters: According to the Nautal Docs documentation, it is compatible with the Perl POD standards. See: naturaldocs.Org/documenting/reference.

Html#Comments and look for Perl POD – FrustratedWithFormsDesigner Feb 10 '10 at 19:17 This looked really nice, but it doesn't pull out the comments and organize them. (Very easy to set up and pretty output, though.) – Benjamin Oakes Feb 10 '10 at 20:24 @Benjamin Oakes: Ok, I admit I've never used it for Perl. I use it for documenting PL/SQL.

It has its problems, but it's by far the best PL/SQL documentation tool I've seen so far. – FrustratedWithFormsDesigner Feb 10 '10 at 20:50 Yeah, it's definitely good to know about. I'm kinda frustrated about documentation because this project I'm working on uses 5 or 6 programming languages.

A unified documentation tool would be great. – Benjamin Oakes Feb 10 '10 at 20:55.

I cant really gove you an answer,but what I can give you is a way to a solution, that is you have to find the anglde that you relate to or peaks your interest. A good paper is one that people get drawn into because it reaches them ln some way.As for me WW11 to me, I think of the holocaust and the effect it had on the survivors, their families and those who stood by and did nothing until it was too late.