I've been religously adding TWiki pseudo-POD documentation, but I have a few problems with it:

1. POD is very crude. Because of the way it works, the code ends up very messy (column 1), it doesn't respect indentation, it doesn't understand the code, it is really little more than a way to interleave hand-written docs with code
2. The use of TWiki formatting is OK, but there's no standards for (for example) the level of subs, how packages look etc.
3. The TWiki POD "standard" is a pain to use with proper POD
4. The PodPlugin can only be run from a system that has the code installed, and is therefore useless for statically extracting docs from sources. And it doesn't even use POD!

Having used Doxygen and JavaDoc extensively in the past, I can't see why we can't have something similarly powered. Some of the things these processors do:

1. Check the parameters in the doc against the function declaration
2. Insert any undocumented parameters
3. Automatically convert method cross-references to links
4. Automatically prettify variable names
5. Allow sensible indentation (none of this "column 1" crap that POD requires)
6. Extract documentation from all sources in a source tree, and compile it into a nice book.

It's really not that hard to provide all this. Can we please have a smarter documentation tool that can do all these things - and can be called from the command line, please, like proper POD? It would need to be compatible with the existing PodPlugin, and existing POD docs in plugins (which use the POD =begin text standard).

Does anyone feel up to the challenge?

-- CrawfordCurrie - 05 Oct 2004

have you seen pdoc?

also, if twiki moves to a CPAN:TWiki namespace, you'll be able to perldoc TWiki::Func (or whatever)

-- WillNorris - 05 Oct 2004

I hadn't but I think the same thing can be done a lot more simply by just generating TML. The tricky bit is guessing what the parameters are to a perl function, though TWiki is pretty consistent about that so it shouldn't be too hard.

-- CrawfordCurrie - 05 Oct 2004

Could we have PerlDocPlugin activated so that pages like MetaDotPm are useful?

-- MeredithLesly - 24 Mar 2006

The PerlDocPlugin is installed on TWiki.org, see InstalledPlugins.

-- PeterThoeny - 24 Mar 2006

Then why is MetaDotPm doc-less?

-- MeredithLesly - 25 Mar 2006

It shows the pod docs of the TWiki currently installed on TWiki.org.

-- PeterThoeny - 25 Mar 2006