Re: Documentation requirement (was [Call For Votes] PHP::Fork)

I would like to suggest an amendment to the package and documentation rules. 1) the initial release of a package at pear.php.net may not be stable. There is inherently potential for bugs caused simply by the complexity of the packaging and installation procedure of PEAR. 2) a package is considered stable ONLY if it has both documentation and unit tests, regardless of the perceived code stability. 3) a package is considered alpha if it has neither documentation nor unit tests, regardless of the perceived code stability. 4) A beta release must have stable documentation - beta means API is frozen until the next stable release. 5) a requirement for package acceptance must be complete inline documentation - peardoc documentation is only required for a stable release and recommended for a beta release Of course, I have a gift for using way too many words to describe something, if these ideas could be pared down to a few words, I would welcome the edit. My main point is that it is simple enough to generate peardoc from inline documentation, that the requirement of docbook docs is really just a requirement for inline docs compatible with phpDocumentor. I agree with others that an alpha release may not benefit from having full documentation at pear.php.net - alpha means nothing is set in stone yet. However, I feel strongly that pear's issue is in fact allowing stable releases BEFORE they are documented. How can a release be stable if it is possible to use experimental elements within the stable release without realizing it? Documentation serves to clearly define the API that should be used, and so is obviously a requirement for stability. Note that my views have changed recently from greater experience - I think alpha releases should have in-code documentation completely up-to-date, and beta releases should have a frozen API, allowing more definitive, stable documentation. I apologize to those I have terrorized about documentation in the past :) Klaus Guenther wrote:

I have two packages that are as yet undocumented, though they have sufficient inline docs. I'm still waiting for Greg's answer about inherited methods and phpDocumentor.

Sorry about the delay - I've been a lot busier than usual, and in fact will be almost completely out of commission until Dec. 3. I'll be able to answer emails that don't require any coding, but even that might be delayed due to travel with the quartet to Texas, Vermont, and Maryland. If you wish to inherit documentation, I would recommend simplying parsing the HTML_Common package in the installed directory along with your package. In other words, either use an ignore parameter to ignore the other files in the directory, or do a special install with only the files you wish to document. Generate your docs directly into the peardoc dir, but be careful to delete your local copy of HTML_Common docs. This is very important! Otherwise you will overwrite the existing docs when you cvs commit :). If you do this, it will automatically generate the correct linking to inherited classes. If you encounter any problems, then you have found a bug. The peardoc converter relies on the position of docs at package.category.package.classname.methodname.xml. This won't hold true for the PEAR or PEAR_Error package, so you would need to manually adjust them to be core.pear.pear and core.pear.pear-error Greg