Autogenerated Code Docs

pileofrogs has asked for the wisdom of the Perl Monks concerning the following question:

This question is 100% inspired by ady's question What is your practice for code documentation?.

Are there good tools to automatically generate docs for code in perl? I use Test::Pod::Coverage to make sure I've written the docs, but it would be awesome if there was a tool that would write up a skeleton that I could then fill out.

--Thanks
Pileofrogs

Comment on Autogenerated Code Docs

Replies are listed 'Best First'.
Re: Autogenerated Code Docs by samtregar (Abbot) on Jun 25, 2008 at 19:29 UTC
Resist the urge. If you're too lazy to write the skeleton (which in POD shouldn't be more than a few lines) then you're way too lazy to write the docs. Once you've got the skeleton your POD coverage tests will probably start passing and you'll lose all interest in filling it in! Trust me - I've worked on projects that used documentation skeletons and 90% of the time they were left empty. -sam	[reply]
Re: Autogenerated Code Docs by Your Mother (Archbishop) on Jun 25, 2008 at 19:02 UTC
I wrote one a few years back that just dumps a bunch of Pod stubs into a given script (if it has no Pod currently). It's primitive but saves typing. You could do the same in 15 minutes, no doubt. What I might try to do (or maybe someone else as I'm swamped) is do a deeper one that perhaps uses PPI and version and such and only fills out the missing parts alla Perl::Critic's "brutal" recommendations and put it up on the CPAN as a script. Though, adding stubs for subs could actually be seen as a problem. If you did that, your Test::Pod::Coverage tests would pass even though there was really no documentation for the subs, just naked =item listings. A command line script to do this should allow for things like --inline (versus after __END__), --license, and the other sorts of things that might keep people from using it because it rubbed against the grain of their personal styles.	[reply]