[sf-perl] javadoc for perl?

[Mike Friedman]

Russ,

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?

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

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. 

Usage:
    my $model_uri = $entry->get_model_uri();

=cut

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/

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
frimicc at gmail.com

On Jan 14, 2013, at 5:46 PM, Russ Tremain <russt at releasetools.org> wrote:

> 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 OODoc and it seems to be headed in the right direction, but is not nearly as nice as javadoc.  Here 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.
> 
> -Russ
> _______________________________________________
> SanFrancisco-pm mailing list
> SanFrancisco-pm at pm.org
> http://mail.pm.org/mailman/listinfo/sanfrancisco-pm
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.pm.org/pipermail/sanfrancisco-pm/attachments/20130114/f055fd47/attachment.html>