Re: [ANNOUNCEMENT] HTML_QuickForm_ElementGrid-0.1.0 (alpha)Released.

Troy Cregger wrote: > » End-user documentation > > No end-user documentation is available for this package. > > » API documentation > Auto-generated API documentation for each release is available. > > http://pear.php.net/package/HTML_QuickForm_ElementGrid/docs/latest/ > [Leads to a blank page] > > Great, yet another totally undocumented PEAR package. > > {begin rant} > Is there any documentation project going on for PEAR? If the API docs > are "generated from in-line comments in source code" then is there > anyone even asking devs to use properly formatted comments so we have at > the very least the damn API docs? > > I like pear allot, it's handy and easy to work with for the most part > but when a package has no documentation *at all* I'm not about to waste > a day figuring out a black box. > > Because of this, I'm probably loosing out on most of the benefit of > using PEAR in general, which is really starting get annoying. > > As a programmer I know that it's way more fun and cool to write code and > make things work than to write about code and how it works *but it's > still gotta be done!* > {end rant} Hi Tony, auto-generated docs are processed by a cron job, and this happens once per day. Your message was set 30 minutes after the release, which explains why they have not been auto-generated yet. The enduser documentation is a problem. I have been pushing quite a bit on this point, and documentation is starting to be written, but it will take a while, half of PEAR is undocumented, and there are very few developers who are willing to take the time to document code that they have not written. It is required to have end-user documentation for stable packages only. Incidentally, if you are using a package marked "alpha" there is some chance that it could change radically on the next release, and break code you've written using it. It is sometimes safer to examine the code directly in these cases. For instance, the PHP_Parser package will be changing dramatically once I find the time to implement a new parser written using PHP_ParserGenerator (which is also alpha and may change dramatically) So, your rant is noticed, and there is work being done, but we do need much more help to get the job done. Thanks, Greg Greg