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

Hi, I know how to write documentation using phpDocumentor, but I'm not willing to write tutorials unless a package is accepted. The current documentation shows what the package does and how to achieve this. If it's accepted, I will write documentation for the website... The most methods provided should be self-explanatory with the documentation that is included... I think most important are some examples, that explain things like how to use countTagsInDepth() to count recordsets in an XML document with a fixed structure. But as pointed out, this will be added after the package has been released. Stephan > -----Ursprüngliche Nachricht----- > Von: Stan Lemon [mailto:insyder@myrealbox.com] > Gesendet: Dienstag, 9. September 2003 13:34 > An: Stephan Schmidt > Cc: pear-dev@lists.php.net > Betreff: Re: WG: [PEAR-DEV] [Call for Votes] XML_Statistics > > > 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 > > >