While I personally don't have a problem with this being the case (I mean.. it seems like a logical behaviour), apparently, parsing package names into a tree is now an expected feature, given
IMHO, it would be best if "folders" with just one item are collapsed into a single package, but I realize this may be performance costly, so if we revert to pre-beta behaviour, that's fine too.
In considering this user's expectation, alongside thinking of the same code example had namespacing been used rather than PEAR naming, I think the furthest I would pursue this idea would be having some runtime option to allow elements to be rolled up into one top-level, maybe one one sub-level, but no deeper than that. For namespaced code, it seems reasonably feasible in my mind to implement. For "packaged" code, not so easy, because now people will expect you to handle all these permutations: @package TopLevel + @subpackage NextLevel; @package TopLevel_NextLevel; no package, but class name is TopLevel_NextLevel_TheClass. Suddenly it's up to phpDocumentor to figure out how to parse through names, some that include some delimiter, and make decisions on how the user intended to structure his groupings.
I'd prefer to keep package-based code's organization as the responsibility of the user, based on his use of @package and perhaps @subpackage. If a runtime option to choose a specific level of grouping for namespaced code is desired, even if it's arbitrarily deep rather than limited to two levels like my earlier comment, there is a reasonable way to do this, but only for namespaced code. Trying to do for package-based code will require some kind of voodoo that will have us effectively creating our own DSL to define what we'll accept and not accept.
That's kind'a the reason @subpackage is deprecated you know...
EDIT: Yeah... f subpackage!
Heh, I had not seen that Mike had put delimiter capability into @package itself. So, that DSL has already been defined for packaged-based code. In that case, the feasibility of defining at runtime just how deep you want phpDocumentor to be allowed to group elements is likely the same complexity for packaged-based code as it is for namespaced code. So, aside from factoring in how to handle @subpackage too (?ignore it?), my earlier concerns no longer apply.
The OP of this issue is posting my issue from stack over flow :D - aside from thatr, are you saying what I see is normal behaviour for PHP Documenter? is this not .... messy?
If you want non-messy, it's best to use namespaces instead of packages.
If you don't want to use namespaces, phpDocumentor accepts "\" as part of the package name, making them namespace-like. I haven't tried if the latest version parses THOSE into folders, but pre-beta, we used "_" as a delimiter when the package did not contain any "\". Not doing that last kind of transformation is IMHO not messy given the option to use "\", but given how many packages in the wild already use this kind of separator, I'm OK if we revert to that old behaviour, which is why I posted your issue.
Packages are handled identically to namespaces when separated by \. They do not create folders and subfolders in the packages or namespaces folder but instead create dot-separated filenames.
So a package My\Package becomes packages/My.Package.html.
Package and subpackages are combined into one package entity.
The _ and . characters are intended as an unofficial alternative to the \ separator but apparently the router does not convert those into dot separators. This should be fixed with this issue
#1020: Fix generating of filenames when packages contain an underscore
And .. fixed. Before closing this issue I will want to check the package HTML contents at a later moment. For now is the reported issue fixed in the develop brach