@package overhaul in PEAR RFC

Hi, One of the shortcomings of PHPDoc and of PEAR is its limited @category/@package/@subpackage tags. Packaging is not a language feature in PHP the way it is in Java, and so only applies to documentation. In the current version of phpDocumentor, there is an illogical possibility of having a class in one package reside in a file that belongs to a different package. I don't like this, and it creates tons of confusion that must be fixed soon. I'd like to propose a major re-organization of both PEAR and the PHPDoc comments. Basically, it would make a great deal of sense to re-organize the CVS of PEAR into the same categories that its documentation is organized into. The impact on individual developers would of course be somewhat minimal, but I know how hard it is to move directory structures in CVS. This would not need to affect installation or end-users at all. However, this would allow automatic category and package determination based on the directories, file names, and class names. For version 2.0 of phpDocumentor, I want to do away with @package/@subpackage altogether, if possible, and instead do packaging in a manner more similar to JavaDoc. What I envision is having a class that encapsulates the packaging logic. A command-line switch would be used to select the package determination class. This will allow flexible packaging on a per-repository/per-package basis. phpDocumentor is a collection of packages, and so writing a class that would determine package from the directory that things are in would be simple and very useful. This system would also allow any flashes of future brilliance that create better ways to package to be accomodated. One great thing that these changes should make possible is to automatically determine package dependencies and construct an include statement that allows usage of a package to be generated by the documentor. This would help end users quite a bit ("to use HTML_QuickForm, include('HTML/Common.php')..." etc. etc.). It would also make it possible to generate documentation for a new package without parsing the entire PEAR repository, as linking could be guessed based on class name. Any comments/caveats? Greg -- phpDocumentor http://www.phpdoc.org