Re: Documentation..
| From: | Lukas Smith | Date: | Tue, 16 Nov 2004 08:47:15 +0000 |
| Subject: | Re: Documentation.. | ||
| References: | 1 2 3 4 5 6 7 8 9 | Groups: | php.pear.qa |
| Request: | Send a blank email to pear-qa+get-1950@lists.php.net to get a copy of this message | ||
Greg Beaver wrote:
Paul M Jones wrote:Missing API documentation is a violation of the PEAR CS.On Nov 15, 2004, at 9:59 PM, Greg Beaver wrote:no API docs is a bug. No verbose tutorials is a feature request. Would you say that PEAR_PackageFileManager has no documentation? It is 99% API docs, but as a part of API documentation, there is a usage example for important methods. The two kinds of documentation are not mutually exlusive.David Costa wrote:<opening mouth> I think we mean end-user documentation here, not just API docs, to include short narrative description (3-4 sentences or a couple of paragraphs?) and getting-started examples. <closing it up again>David Costa P.S. we can open a bug report for every non documented package in the stable branch.. if that helps...very good. lack of documentation for anything "stable" is by definition a bug, because the API is not defined, so BC is already broken any time a bug is fixed :)
I like tutorials, but they are not essential to understanding 99% of packages. What really matters is knowing how to use a method/class and what the expected usage is. The rest is candy for people who are also learning how to program at the same time.Most packages have examples .. even several. I think we need to bring the Costa's script back to visibility (I assume its been a long time since anyone submitted anything). Then we should facilitate placing in direct view links into cvs.php.net to all of the examples into the documentation. Adding a few more comments into the examples and viola .. wie have API documentation and plenty of tutorials. regards, Lukas