[sf-perl] javadoc for perl?

[Russ Tremain]

At 10:04 PM -0800 1/14/13, Mike Friedman wrote:
>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?

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 
<http://search.cpan.org/~darnold/Pod-Classdoc-1.01/lib/Pod/Classdoc.pod>Pod::Classdoc 
by Dean Arnold which seems to have a lot of what I want.. and it 
integrates with Pod-ProjectDocs ...

thanks,
-Russ



>
>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/>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. 
>><http://perl.overmeer.net/mimetypes/html/jump.cgi?MIME_Types&42>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
>><mailto:SanFrancisco-pm at pm.org>SanFrancisco-pm at pm.org
>><http://mail.pm.org/mailman/listinfo/sanfrancisco-pm>http://mail.pm.org/mailman/listinfo/sanfrancisco-pm
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.pm.org/pipermail/sanfrancisco-pm/attachments/20130115/ae13b95c/attachment-0001.html>