Option not to use packages in class URLs?
nathanl opened this issue · 6 comments
Many of our classes do not yet have packages assigned, but all of them have unique names based on the code's directory structure, like "class Somedir_Subdir_Classname". For us, it would be ideal if the documentation fell into the same directory structure instead of "packagename/classname." Besides which, using the package name in the URL means that the URL will change as we add @Package information in the future.
- Would customizing this require changing code in many places, or just classWriter?
- Would you consider making URL path a config option, or would we have to branch the code to do this?
I haven't looked, but off the top of my head this should be possible simply from the classWriter in the standard doclet. It should be pretty easy to add a config switch that makes it take the class path into account if no @Package is found (ie. it's in the default package).
If you wanted to attempt to add this, that'd be great. Otherwise I'll add it to my todo list.
I would love to add this - would be fun to contribute. Let me see what I can do and I'll get back to you.
Well, I'm stumped. I would love some help if you have time.
Here's what I'm trying to do, per my team's wishes. Not sure if this would be useful for others or not.
Our classes' names are structured to indicate their paths, which makes them easy to autoload. So if we had a class for pumas, it might be in "base_includes/libraries/mammals/cats/mammals_cats_pumas.php." The class itself would be "class Mammals_Cats_Pumas".
What I'd want to do for the documentation is completely ignore the @Package tag, because some classes have them, some don't, and there's never been consensus on whether or how they should be done. Instead, I want to derive this class's package from its name.
I have successfully gotten the actual documentation files to follow our original directory structure, so that both the page where you look at a class and its methods and the page where you see its source code are named this way. I did this by changing ClassWriter, starting at line 270:
// The normal way of building up the path
//$this->write($package->asPath().'/'.strtolower($class->name()).'.html', $class->name(), TRUE);
// Build it up from the name instead
$className = $class->name();
$filePath = substr(preg_replace('//','/',$className),0,strrpos($className,'_') + 1);
$this->_write($filePath . strtolower($class->name()).'.html', $class->name(), TRUE);
So the resulting filenames are fine. (Actually I should tweak that to use just the substring before the first underscore, but this does make the path write out differently at least.) But the links to that file are wrong, and it is still considered to be part of whatever package its @Package tag shows.
What I'd like to do is find the place where the @Package tag is originally read, and say, "you know what? Ignore that. If the class name is 'Mammals_Cats_Pumas', just use 'Mammals' as the package name." I tried to set the package name this way by modifying phpDoctor.php around line 580, but anytime I tamper with that string, I end up with a null object later when I should have an instance of PackageDoc, and it tries to call asPath() on line 100 of indexWriter.php and has a fatal error.
So: is there a way that I can override the reading of the @Package tag and make it use a substring from the class name instead? If I can do that in one central place, I think everything else will just work, but darn if I can see where it should be done.
Sorry if this goes against what you intended for the project, but it's the way my team wants their documentation. Thanks VERY MUCH in advance for any help you can give.
I've added two new config options, one for suppressing @Package tags and the other for setting the default package on the filepath of the current file. Give it a try and see if it does what you need.
Yes! That's awesome! It does exactly what we need. Thank you so much!
Do you take monetary contributions on this project? Since I wasn't able to add this feature myself, I'd like to chip in somehow.
Improvement of the code is reward enough. If you want to help, use the code, find bugs, and submit patches.