Re: coders: add doco

I'm still catching up on backlogged mailing list mail here, but just to 
try to be helpful-

Like many folks who lurk on this list, I have limited time to do detailed 
work on parrot internals, much as I would like to.

But I am always excited when there's an opportunity to do simple, menial
tasks that help our more active contributors to be more productive.

If someone can tell me what the documentation standards should be, i'll be 
happy to either devise a program to try to check it (like 
check_source_standards.pl does for our coding standards) or manually 
review and prod folks to help get our documentation up to standards.  

But before I can do that I need to know what the end goal is.  In general, 
Are we shooting for literate code, or separate documentation from code?

Along the same lines, what documents are we looking to generate?  
Per-file docs?   One big developers guide?   (If so, how is it divided up)

Are POD directives to be used for things other than strictly docmentation? 
(=for API?  did that go anywhere?)

Do we want POD for every function?   Every non-static function?

Are there simple guidelines we can use to programatically identify 
trouble spots?
  - a certain comments/line of code metric
  - a readability metric (Lingua::EN::Fathom) for our comments?

Etc..

IMHO, all this needs to either go into pdd07 or into a new pdd.  I hate to 
bounce this back to the designers, but I don't think I have enough 
experience, perspective, or authority to make any of these decisions in a 
vacuum.

--Josh

• coders: add doco by John Porter
• Re: coders: add doco by Melvin Smith
• Re: coders: add doco by John Porter
• Re: coders: add doco by Mike Lambert
• Re: coders: add doco by Josh Wilmes
• Re: coders: add doco by Eric Kidder