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

Sorry posted with the wrong e-mail address before: -------------------------------------------------- First off, didn't say you don't how to write docs with PhpDocumentor, I only said your are uncomplete in this package. It's not only tutorials that need to written though, but the inline comments tell the user nothing. There should be more description then the name of the tag, and the name of the tag in sentence form. There are so many PhpDocumentor tags that you are not using which could really help your case. Examples are nice, but if you don't explain step by step what is going on in each example they do not benefit. Plus the tutorial(s) should have an overall example, and then running explanation of it. I see the exscuse that docs will be added after acceptance as a reason not to accept the package. Granted, good purpose, and the package seems decent, but it is undocumented and I don't know how willing I would be to say "Ok, well the docs get done after package acceptance" because they simply might not get done. The docs should be there, and this package should not get accepted until you as a developer takes responsibility and has respect for the people that will be using it, and that's what this ammounts to really. Sure, PEAR developers may be able to handle the code, but was PEAR developed solely for PEAR developers, or the entire PHP community? - Stan Stan Lemon wrote:

In all honesty I would like to see some work done on the documentation. As of this point the package suffers from the same disease that most of PEAR does, yes it has inline comments, but it doesn't tell me how to use the package. Granted some of it is self explanatory, e.g. getMaxDepth (line 399) get the maximum nesting level

    * return: maximum nesting level
    * access: public

integer getMaxDepth () However, you could still elaborate and get more indepth on it. I'd also suggest that in addition to the method comments you work on the package and file level comments also. And most importantly... Develop a tutorial. If you are unfamiliar with phpdoc's tutorial system then read up on it, because it's really great. If you develop these docs well enough then in PhpDocumentor 1.2.2.1 you can generate peardoc2 and you're all set as far as the PEAR web site goes. So for now I don't support this package, simply because the documentation is incomplete. I follow the motto that the best package is still the worst package if no one knows how to use it. PEAR has to undocumented packages as is, it doesn't need another one. Outside of the documentation I like the package though. Good luck, - Stan Stephan Schmidt wrote:

Hi, Thanks for your comments and your vote.

* CS: - Private class members must be prefixed with _

I guess you are referring to the options, I'll change this before I release it.

* Examples need to be fixed: - for the include: 'XML/Statistics.php' - example file input: 'example.xml' - put \n after each <br> to help when looking at the source or running from the command line. And so on. - Comment the examples so people know what everything does - example3.php needs to mention that it requires the Math_Stats package

I planned to work on the examples before the fist public release, the included files were just quick hacks to test it myself... Stephan