On 5 Aug 2007, at 17:46, Jesse Ross wrote: > One thing I would say counter to this, where comments are extremely > important, is the API documentation. PHP and Actionscript, the two > languages I use most often, use an "official documentation followed > by comments" model, and I find that very useful. Oftentimes the > comments have more useful real-world examples and better explanations > than the docs themselves, so I would like to see that model continued > on our site as well.
I tend to think the opposite with PHP. They seem to use the comments section as an excuse for the documentation to suck. I would much rather people file bug reports where our documentation is bad. Some people will be using PDF versions of the documentation offline, rather than the online version, and so I would rather we focussed on making the official documentation good than relied on other people to fill in the gaps. If you compare the Cocoa documentation, or even MSDN, to PHP, then the PHP documentation is embarrassingly poor quality. As a user of the documentation, I'd much rather not have to wade through a dozen people discussing the correct way of using a function; I want the correct use to be at the top of the documentation. David _______________________________________________ Etoile-discuss mailing list [email protected] https://mail.gna.org/listinfo/etoile-discuss
