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
