Re: phpDocumentor Docs for most of PEAR

One thing that is not clear to me is that, for example in the case of some unit test scripts for Math_Stats, I see: test_Math_Stats_instance_methods.php Warnings: Warning on line 41 - no @package tag was used in a DocBlock for class Math_Stats_UnitTest Warning on line 893 - no @package tag was used in a DocBlock for file /usr/share/pear/Math/test/test_Math_Stats_instance_methods.php Errors: Error on line 27 - require_once include's DocBlock has @package tag, illegal. ignoring tag "@package Math_Stats" Error on line 27 - DocBlock has multiple @package tags, illegal. ignoring additional tag "@package Math_Stats" I am not too sure why the parser thinks that it is an error. It is not the way a package is used in Javadoc IIRC. Each file that is in a package must have that label, irrespective of the other classes that are imported also contain that. Of course in Java is simpler as there is a 'package' declaration. Using the logic of your parser, if I have a script bar.php form the package Cool_Foo.php that includes first Foo.php (that has @package Cool_Foo) and then also includes Math/Stats.php (that has @pacakage math_Stats), would that generate and error? What would be the package automatically assigned to bar.php? Cool_Foo? or Math_Stats? This is something that I am not sure I understad the logic behind in the way phpDocumentor. Also the warnings about @package not being in a docblock seems to me spurious, as (again) following the javadoc style, is usually put right before the class contained in a file, not by itself. For example phpDocumentor says: Macromolecule_PDB.php Warnings: Warning on line 83 - no @package tag was used in a DocBlock for file /usr/share/pear/Science/Chemistry/Macromolecule_PDB.php Line 83 is the last line in that file. And the correspoding lines say at before the class definition are: ... require_once "Science/Chemistry/Macromolecule.php"; require_once "Science/Chemistry/Residue_PDB.php"; /** * Represents a PDB macromolecule, composed of several * Science_Chemistry_Residue_PDB objects * * @author Jesus M. Castagnetto <jmcastagnetto@php.net> * @version 1.0 * @access public * @package Science_Chemistry */ class Science_Chemistry_Macromolecule_PDB extends Science_Chemistry_Macromolecule { ... I would consider that a bug in phpDocumentor not to notice the @package there, and only force it to be at the top of the file in a *separate* documentation block, e.g.: /** * @package Science_Chemistry */ ... etc ... Just minor annoyances on great documentation tool. --- Joshua Eichorn <jeichorn@joshuaeichorn.com> wrote: > I generated api docs for all of PEAR that would install right through > the installer. > Its the stable version of the majority of packages, but its the PEAR > install on my workstation so you get the beta in a couple cases since i > needed the new bugfix, or I'm testing a new feature. > > Everything is at: http://phpdorks.net/docs/api/ > > If you maintain a package and don't see it installed you can look at my > pear list-all output, i installed everything I could > so if your not package isn't there its cause your install is messed up > or your a PECL package that needed a lib. > > Also checkout: > http://phpdorks.net/docs/api/docs/api/pear/errors.html > > There are a ton a warnings generatating the docs and quite a few errors, > getting hte errors fix would be a good thing, > > Especially in XMLTransformer and Speadsheet Excel Writer, both of these > use empty @param or @return tags > in a normal phpDocumentor setup errors this bad will stop the > documentation generation. > > And finally the docs were generated with phpDocumentor 1.2.1 (or what > will become 1.2.1) with errors that stop parsing commented out. > > Also this template doesn't work all that well for 120+ packages i'll be > working on a new template in the future that covers this case a little > better. > > -joshua eichorn > phpDocumentor project admin > http://phpdoc.org > > > > > -- > PEAR Development Mailing List (http://pear.php.net/) > To unsubscribe, visit: http://www.php.net/unsub.php > ===== -- Jesus M. Castagnetto (jcastagnetto@yahoo.com) Research: http://metallo.scripps.edu/ Personal: http://www.castagnetto.org/ __________________________________ Do you Yahoo!? SBC Yahoo! DSL - Now only $29.95 per month! http://sbc.yahoo.com