Re: PEAR Documentation useless while ...

On Mon, 09 Aug 2004 22:40:38 -0500, Alfonso Baqueiro <abaqueiro@memoria1.com> wrote: > The documentation in pear site is the kind of API documentation, like > the java api documentation, but in fact that kind of documentation is > only useful if you have a knowledge of the purpose of the clases and the > problem that they try to solve. > > Another failure in the documentation is there are a lot of packages that > does not have documentation. > Not all documentation is the same. Much of the documentation has examples and explanations of what the class is for. In addition, some have external websites with these things. Many also have examples in their tarballs. If you're only clicking on the API Documentation links instead of the End-User Documentation links, that's why it's all API-like docs. If all you find for a class is API-like docs (some End-User docs *are* like API docs) then often examples are in the tarball, in the code, or can be found by Googling. Please don't say *all* when you haven't looked at *all* of the docs. > The utilization of PEAR repository can be improved if is included in the > documentation some examples of utilization of the classes solving real > problems, an example is more useful and educative and can give a fast > general vision of the class utility, that allows to the people using the > class to hack the code for search details of the class. > > Other important aspect that can be a plus is if the classes include > anotations on the analysis of the problem, design decisions, the > problems find in the implementation and the clever ideas that allow to > round the problems. Some do have these kind of things. You can find more by looking at the comments in the source, looking at the CVS commit messages, and searching the PEAR-dev mailing list. If you still don't find what you're looking for, ask on the PEAR-general or dev lists depending on if you want help using the package or design questions, respectively. > > With who can i discuss this kind of things? The PEAR-dev list is a great place to post questions to. You often can get lots of answers from lots of people. Most developers subscribe to this list and will see you messages. If you really want to know something specific about a package you can also try e-mailing the developers listed for a package, but normal questions should be addressed to the PEAR-dev list. -- DB_DataObject_FormBuilder - The database at your fingertips http://pear.php.net/package/DB_DataObject_FormBuilder paperCrane --Justin Patrin--