Re: AW: AW: WG: [PEAR-DEV] [Call for Votes] XML_Statistics

In some classes the constructor is used to set options, make connections, etc. By looking at your docs I would have no idea whether or not it does that. Yes, it instantiate's the class, but does it do anything else? Documentation needs to specify what a function does and does not do. Your constructor's doc's say nothing about anything. It's incomplete, and as far as that goes useless. That part of the documentation might as well not be there because it serves no purpose. All I'm asking is that the docs be complete, that they serve a purpose, and not merely be inline comments that do nothing. Make the docs do something. Want good examples of documentation? Generate PhpDocumentor's documentation. Is Greg hadn't been so complete PhpDocumentor (as great as it is) would have sucked royally, because I'd be in the dark! Pager_Sliding is a good example of documentation, for the most part HTML_Template_Flexy is good too (On the pear web site, I haven't looked at inline because the peardoc is thorough and complete enough). Refer to those two and follow their example. Katana has a very good and valid point. Don't contribute to the reason why professional won't use PEAR, instead help solve the problem. - Stan Stephan Schmidt wrote:

Hi,

What does the constructor do though? Is static? Is it private?

First off, the constructor creates a new instance, do you want to to write this down in the class? It is public (I use * @access public), and cannot be called statically (I would have put @static there). It accepts no parameters, so what should I explain. There's an example at the top of the file, that shows you how to instantiante it: $stat = &new XML_Statistics();

Also, because you didn't include XML_Parser in your docs generation I don't know what was redefined and so forth. Next round of docs, during generation I'd suggest including XML_Parser.

The generated API doc is just for the developers to approve the package, we do not include HTML doc in the packages. If you generate the documenation on your machine, XML_Parser, if you specify correct folders. Furthermore, it's irrelevant for using XML_Statistics... Stephan