<html><head><meta http-equiv="content-type" content="text/html; charset=utf-8"></head><body dir="auto"><div style="-webkit-text-size-adjust: auto; ">Russ,</div><div style="-webkit-text-size-adjust: auto; "><br></div><div style="-webkit-text-size-adjust: auto; ">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?</div><div style="-webkit-text-size-adjust: auto; "><br></div><div style="-webkit-text-size-adjust: auto; ">I have no comment on POD syntax. It is what it is; you get used to it.</div><div style="-webkit-text-size-adjust: auto; "><br></div><div style="-webkit-text-size-adjust: auto; ">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. </div><div style="-webkit-text-size-adjust: auto; ">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:</div><div style="-webkit-text-size-adjust: auto; "><br></div><div><div><span style="-webkit-text-size-adjust: auto;">=head3 get_model_uri</span></div><div><span style="-webkit-text-size-adjust: auto;"><br></span></div><div><span style="-webkit-text-size-adjust: auto;">An accessor (get only) to get the URI for the Model Document for this entry. </span></div><div><span style="-webkit-text-size-adjust: auto;"><br></span></div><div><span style="-webkit-text-size-adjust: auto;">Usage:</span></div><div><span style="-webkit-text-size-adjust: auto;"> my $model_uri = $entry->get_model_uri();</span></div><div><span style="-webkit-text-size-adjust: auto;"><br></span></div><div><span style="-webkit-text-size-adjust: auto;">=cut</span></div></div><div style="-webkit-text-size-adjust: auto; "><br></div><div style="-webkit-text-size-adjust: auto; ">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.</div><div style="-webkit-text-size-adjust: auto; "><br></div><div style="-webkit-text-size-adjust: auto; ">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></div><div style="-webkit-text-size-adjust: auto; "><br></div><div style="-webkit-text-size-adjust: auto; ">You can have it generate an entire directory recursively and all the links work. Very handy for putting on an intranet.</div><div style="-webkit-text-size-adjust: auto; "><br></div><div style="-webkit-text-size-adjust: auto; ">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.</div><div style="-webkit-text-size-adjust: auto; "><br></div><div style="-webkit-text-size-adjust: auto; ">Good luck!<br><div>-- Mike</div><div>______________________________</div><div>Michael Friedman</div><div><a href="mailto:frimicc@gmail.com">frimicc@gmail.com</a></div></div><div style="-webkit-text-size-adjust: auto; "><br>On Jan 14, 2013, at 5:46 PM, Russ Tremain <<a href="mailto:russt@releasetools.org">russt@releasetools.org</a>> wrote:<br><br></div><blockquote type="cite" style="-webkit-text-size-adjust: auto; "><div>
<title>javadoc for perl?</title>
<div>Is it hopeless?</div>
<div><br></div>
<div>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!).</div>
<div><br></div>
<div>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.</div>
<div><br></div>
<div>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.</div>
<div><br></div>
<div>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.</div>
<div><br></div>
<div>-Russ</div>
</div></blockquote><blockquote type="cite" style="-webkit-text-size-adjust: auto; "><div><span>_______________________________________________</span><br><span>SanFrancisco-pm mailing list</span><br><span><a href="mailto:SanFrancisco-pm@pm.org">SanFrancisco-pm@pm.org</a></span><br><span><a href="http://mail.pm.org/mailman/listinfo/sanfrancisco-pm">http://mail.pm.org/mailman/listinfo/sanfrancisco-pm</a></span><br></div></blockquote></body></html>