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 be able to create the DocTree. -- Regards, MarkOv ------------------------------------------------------------------------ Mark Overmeer MSc MARKOV Solutions m...@overmeer.net soluti...@overmeer.net http://Mark.Overmeer.net http://solutions.overmeer.net
