Hi,
The following facts about POD seem clear from the discussion.
1. POD seems to be the way to go because it is supported by the Perl language
and accepted and understood broadly in the Perl community
2. Inline POD seems to be the way to go because of proximity to the code,
although the existence of external pods is valid supplemental
documentation
(and for translations)
3. POD is very limited (compared to Javadoc, for instance), in that it has no
real ability to (1) parse the actual code, or (2) validate the code
against
the comments
4. POD is limited in the set of things that can be specified
5. POD is limited in the type of output formats (requires coding to create a
new style, not just style-sheeting)
I have the following add-on questions.
1. Wesley - How do we configure the Makefile.PL so that the documentation
gets
separated from (stripped from?) the code at "make; make install" ?
(or did I misunderstand you?)
2. Matt - How do we configure Makefile.PL to invoke Pod::XML at
"make; make install"?
(http://search.cpan.org/doc/MSERGEANT/Pod-XML-0.93/XML.pm)
3. Who among us has written a POD::* module to convert pod to a different
format?
4. What would it take to enhance the core POD capabilities?
5. Does anyone know what Perl6 holds in store for POD and embedded doc?
(i.e. validation against the code, etc.)
I have the following recommendations.
1. Use inline POD where possible and separate POD files where reasonable
2. We need to come up with a commenting/POD convention to allow for
specification
of at least all of the things that Javadoc allows you to specify
3. Standard "make; make install" for a P5EE module should produce man
pages (perldoc),
html pages, PDF, and XML (for further flexible conversion/rendering)
4. Our standard doc generation should produce output at least as nice as
Javadoc
(see an example at
http://java.sun.com/j2ee/sdk_1.3/techdocs/api/index.html)
I have the following actions to request volunteers on.
1. Can someone write up a spec (or an example) on what an "enhanced POD"
file would look like?
(i.e. specifying at least all of the things you can specify with Javadoc)
Stephen
At 09:02 AM 11/12/2001 -0500, [EMAIL PROTECTED] wrote:
>
>
>+ Inline POD. Makes it easier to remember to actually write the
documentation,
>if I write it as I'm writing the code. I can glance through a file of
code and
>see right away if I forgot to document anything. The POD tools can
separate out
>the docs to create a separate document file if that's what you want to end up
>with.
>
>--Wesley
>
>Stephen Adkins <[EMAIL PROTECTED]> on
>
>Hi,
>
>What experiences to people have with using inline POD within
>the Module.pm as opposed to maintaining two files,
>Module.pm (for code) and Module.pod (for documentation)?
>What recommendations would you have for P5EE code?
>
>I would assume Inline POD is the way to go.
>I am wondering if anyone has experiences counter to this.
>
>Stephen
