[sf-perl] javadoc for perl?
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
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:
>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:
>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.
><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
>>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...
More information about the SanFrancisco-pm