[sf-perl] javadoc for perl?

Russ Tremain russt at releasetools.org
Tue Jan 15 10:35:31 PST 2013

At 10:04 PM -0800 1/14/13, Mike Friedman wrote:
>Is your complaint with POD that it's a weird format, that it doesn't 
>auto-generate POD with method signatures, or that the HTML output 
>looks different?

not so much a complaint as a question about how I could create more 
useful documentation, using constructs similar to javadoc.

>I have no comment on POD syntax. It is what it is; you get used to it.

faint praise indeed.  :)

I'm looking at 
by Dean Arnold which seems to have a lot of what I want.. and it 
integrates with Pod-ProjectDocs ...


>I've never liked POD-generating programs, but that's personal 
>preference. There are several modules on CPAN that will generate POD 
>for you, based on either a shorthand or the code itself.
>In my case, I just put POD above each function in the code. You 
>stick a standard header at the top of the file and then document 
>each method in place, such as like this:
>=head3 get_model_uri
>An accessor (get only) to get the URI for the Model Document for this entry.
>     my $model_uri = $entry->get_model_uri();
>I highly recommend using a template for each sub, containing all the 
>information you'll want in the output. When you generate output 
>everything will be in document order, so all the methods will be 
>documented in the right place.
>As for HTML output, I've had good luck with Pod::ProjectDocs: 
> <http://search.cpan.org/~lyokato/Pod-ProjectDocs-0.40/>http://search.cpan.org/~lyokato/Pod-ProjectDocs-0.40/
>You can have it generate an entire directory recursively and all the 
>links work. Very handy for putting on an intranet.
>In any case, you can always write your own POD-like parser, either 
>to generate POD or to generate prettier HTML output. That's a bit of 
>work, but you can get to 50% really quickly, I would expect.
>Good luck!
>-- Mike
>Michael Friedman
><mailto:frimicc at gmail.com>frimicc at gmail.com
>On Jan 14, 2013, at 5:46 PM, Russ Tremain 
><<mailto:russt at releasetools.org>russt at releasetools.org> wrote:
>>javadoc for perl?
>>Is it hopeless?
>>I used to do a fair amount of java programming, and one of the 
>>things I miss, when working on OO perl code, is javadoc (especially 
>>working on someone else's OO perl!).
>>I don't know why, but pod format seems very unnatural to me for 
>>documenting OO perl.  It reminds me more of nroff.  I prefer having 
>>the doc more tightly coupled with methods/packages/functions.
>>I've looked at some of the output from 
>><http://search.cpan.org/~markov/OODoc-2.00/lib/OODoc.pod>OODoc and 
>>it seems to be headed in the right direction, but is not nearly as 
>>nice as javadoc. 
>>is some example output.
>>Thoughts?  Generate psuedo java code from OO perl and run it 
>>through javadoc maybe?  Probably the other way (generate perl OO 
>>from java class stubs with doc) would be easier, but I don't think 
>>it is sellable to a perl development team.
>>SanFrancisco-pm mailing list
>><mailto:SanFrancisco-pm at pm.org>SanFrancisco-pm at pm.org
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.pm.org/pipermail/sanfrancisco-pm/attachments/20130115/ae13b95c/attachment-0001.html>

More information about the SanFrancisco-pm mailing list