Being on holidays, it is not easy to follow threads closely, so if
I repeat things other people have said already, I apologize beforehand.
My responses may b late as well.
Two years ago, I discussed various options, which compared POD to features
in to other languages and suggested various syntaxes:
http://www.nntp.perl.org/group/perl.perl6.language/2007/07/msg27894.html
What I did not really find back in the (swift) scan of the whole debate
gongin on at the moment, is the need to maintain *error free*, *complete*,
and *consistent* documentation with *minimal effort*. So: the purpose of
documentation. This must be clear before syntax is being discussed.
"Error free" is simpler in Perl5, because subs have simple parameter
prototypes and we have no strict types. In Perl6, when the user
has more power in the parameter list, it is harder to document it
correctly by hand.
I have experiences converting two large existing modules from
'POD at the end' into 'intermixing POD and code'. I found many,
many mistakes in the POD probably because when changing the code
later, people do not see where the docs which need to be updated
are located.
POD at the end of the code to allow a logical flow of the docs has
some advantanges. IMO however, you mix two different needs of use
for documentation: you wish to teach the user and you need to describe
the API.
So, why not seperate those two purposes more clearly? My code
always has a rather short DESCRIPTION chapter, then the "use often"
detailed METHOD or FUNCTION description (interleaved with code)
and then a DETAILS (maybe a bad name) which is the training bit:
how everything interacts without going into the disturbing API
nitbits.
"Complete" is covered only partially by the "POD::Coverage". Of
course, it is detectable whether all methods/subs/rules are
described, but can you also check whether all parameters are
described in full?
"Consistent" documentation is something Perl5 lacks: have a look at
the way different (Core) modules describe their API. One of the
poorest parts is the complete lack of inheritance support for
documenting Perl. If you only write distributions with a single
functional package in them, then POD(5) suffices. When you do
more complex stuff (like the IO:: modules with inheritance etc)
then people start manually maintain lists of inherited methods and
named parameters in higher level man-pages. This is very hard to
maintain an stupid!!
"minimal effort" is crucial: when you want people to write documentation,
then it must create the most useful/beautiful result with minimal
effort. The need to rewrite method call parameters is one the of
useless and error-prone parts of the current POD design. Of course,
there must be a way to overrule the prototype when needed.
As example: my Mail::Box set of modules contain (with depedencies)
about 140 packages with 1150 documented methods and 200 error messages.
I use OODoc to improve PODs limitations which saves me the typing
of 700,000 characters(!) which pure POD would require.
The discussion with Damian, two years ago, is whether POD is a
second class sitizen, where it is a burdon to have it and code the only
important thing, or a first class sitizen. IMO (which is not generally
accepted in the Perl community, but in common in other languages) it is
the latter. IMO programming is solving a problem in a good way, which
means: it is only solved when "it works and is usable".
"it works"
. it does what we need it to do in our application
. it has regression tests to guarantee that the API works
"is usable"
. algorithmic documentation (where the code is unclear)
. api documentation
Code is IMHO not more important that docs or tests; they are different
view on the same problem. And most of use spend much more lines of text
on docs and tests than on the code (I guess three times as many lines
on docs as on code) So:we need a very light syntax for POD!
There are a few sources which could be used for POD:
1) information from the code
2) information from tests
3) interleaved documentation
4) end-of-file documentation
5) Separate file documentation
6) author, license, SEE ALSO, distribution, version facts
We need to have a standard way of translating those into a "document
tree". Then we can have different implementations to serialize that
into MAN, HTML etc. That latter part does not need an obligatory spec.
I use a template system for it. The current Perl6 specs do not follow
this model sufficiently.
If you agree that DOCs are first class language sitizens, then it must
be clear that the "short notation for often used syntax" rule applies.
#{{ or #{ are visually screaming far too loud. I would prefer a
simple /^\s*\`\s+/, but can think of many alternatives.
The link mentioned before refers to a more details spec with examples
to b
