<!doctype html public "-//W3C//DTD W3 HTML//EN">
<html><head><style type="text/css"><!--
blockquote, dl, ul, ol, li { padding-top: 0 ; padding-bottom: 0 }
 --></style><title>Re: [sf-perl] javadoc for
perl?</title></head><body>
<div>At 10:04 PM -0800 1/14/13, Mike Friedman wrote:</div>
<blockquote type="cite" cite>Russ,</blockquote>
<blockquote type="cite" cite><br></blockquote>
<blockquote type="cite" cite>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?</blockquote>
<div><br></div>
<div>not so much a complaint as a question about how I could create
more useful documentation, using constructs similar to javadoc.</div>
<div><br></div>
<blockquote type="cite" cite>I have no comment on POD syntax. It is
what it is; you get used to it.</blockquote>
<div><br></div>
<div>faint praise indeed.  :)</div>
<div><br></div>
<div>I'm looking at <a
href=
"http://search.cpan.org/~darnold/Pod-Classdoc-1.01/lib/Pod/Classdoc.pod"
>Pod::Classdoc</a> by Dean Arnold which seems to have a lot of what I
want.. and it integrates with Pod-ProjectDocs ...</div>
<div><br></div>
<div>thanks,</div>
<div>-Russ</div>
<div><br></div>
<div><br></div>
<div><br></div>
<blockquote type="cite" cite><br></blockquote>
<blockquote type="cite" cite>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.</blockquote>
<blockquote type="cite" cite>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:</blockquote>
<blockquote type="cite" cite><br></blockquote>
<blockquote type="cite" cite>=head3 get_model_uri</blockquote>
<blockquote type="cite" cite><br></blockquote>
<blockquote type="cite" cite>An accessor (get only) to get the URI for
the Model Document for this entry.</blockquote>
<blockquote type="cite" cite><br></blockquote>
<blockquote type="cite" cite>Usage:</blockquote>
<blockquote type="cite" cite>    my $model_uri =
$entry->get_model_uri();</blockquote>
<blockquote type="cite" cite><br></blockquote>
<blockquote type="cite" cite>=cut</blockquote>
<blockquote type="cite" cite><br></blockquote>
<blockquote type="cite" cite>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.</blockquote>
<blockquote type="cite" cite><br></blockquote>
<blockquote type="cite" cite>As for HTML output, I've had good luck
with Pod::ProjectDocs:  <a
href="http://search.cpan.org/~lyokato/Pod-ProjectDocs-0.40/"
>http://search.cpan.org/~lyokato/Pod-ProjectDocs-0.40/</a></blockquote
>
<blockquote type="cite" cite><br></blockquote>
<blockquote type="cite" cite>You can have it generate an entire
directory recursively and all the links work. Very handy for putting
on an intranet.</blockquote>
<blockquote type="cite" cite><br></blockquote>
<blockquote type="cite" cite>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.</blockquote>
<blockquote type="cite" cite><br></blockquote>
<blockquote type="cite" cite>Good luck!<br>
</blockquote>
<blockquote type="cite" cite>-- Mike</blockquote>
<blockquote type="cite"
cite>______________________________</blockquote>
<blockquote type="cite" cite>Michael Friedman</blockquote>
<blockquote type="cite" cite><a
href="mailto:frimicc@gmail.com">frimicc@gmail.com</a></blockquote>
<blockquote type="cite" cite><br>
On Jan 14, 2013, at 5:46 PM, Russ Tremain <<a
href="mailto:russt@releasetools.org">russt@releasetools.org</a>>
wrote:<br>
<blockquote type="cite" cite>javadoc for perl?</blockquote>
<blockquote type="cite" cite>Is it hopeless?</blockquote>
<blockquote type="cite" cite><br></blockquote>
<blockquote type="cite" cite>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!).</blockquote>
<blockquote type="cite" cite><br></blockquote>
<blockquote type="cite" cite>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.</blockquote>
<blockquote type="cite" cite><br></blockquote>
<blockquote type="cite" cite>I've looked at some of the output from <a
href="http://search.cpan.org/~markov/OODoc-2.00/lib/OODoc.pod">OODoc</a
> and it seems to be headed in the right direction, but is not nearly
as nice as javadoc.  <a
href=
"http://perl.overmeer.net/mimetypes/html/jump.cgi?MIME_Types&42"
>Here</a> is some example output.</blockquote>
<blockquote type="cite" cite><br></blockquote>
<blockquote type="cite" cite>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.</blockquote>
<blockquote type="cite" cite><br></blockquote>
<blockquote type="cite" cite>-Russ<br>
</blockquote>
<blockquote type="cite"
cite>_______________________________________________<br>
SanFrancisco-pm mailing list<br>
<a href="mailto:SanFrancisco-pm@pm.org">SanFrancisco-pm@pm.org</a><br>
<a
href="http://mail.pm.org/mailman/listinfo/sanfrancisco-pm"
>http://mail.pm.org/mailman/listinfo/sanfrancisco-pm</a></blockquote>
</blockquote>
<div><br></div>
</body>
</html>