PhpDocumentor vs. Doxygen: Five Reasons I like Doxygen Better
I like the fact that PhpDocumentor is implemented in PHP. I like that it has a mature feature set, and has a long history of support. But when it comes to generating API documentation from PHP, I am preferring Doxygen these days. Here are five reasons why. <!--break-->
1. Doxygen's Default Output is Better
I don't want to have to theme my documentation. I just want to easily generate highly usable API documentation. Doxygen's default template is heads and shoulders above any of the default PhpDocumentor templates. It includes a JavaScript API search, sensible navigation that works well for OO and procedural projects, and doesn't suffer from box overflows or other rendering issues.
2. Doxgen Seems Smarter
For example, I don't have to use @link tags or other explicit references to get Doxygen to recognize that a given word is a class, method, or function. It's examination of the text seems to automatically discover this 99% of the time. It seems to reliably resolve scope issues, too. It also seems more flexible with the input in @param and other tags.
With explicit tags like @file, it is also easier to be clear to the doxygen engine when documenting files (as opposed to elements in the file).
3. Extended Documentation is Better
One of the biggest annoyances of PhpDocumentor was trying to write DocBook-ish documentation for part of the manual, and docblock documentation for another part. Linking between the two was always hard, and many times I just gave up rather than try to figure it out.
Doxygen provides an extended set of @-commands that make it much easier to write extended documentation right inside the source code. Since this are optional, it doesn't introduce complexity unless I want the increased complexity.
4. Doxygen is Highly Configurable
Doxygen's configuration file provides an astounding number of options. There are hundreds of options available for tuning everything from high-level data (title, description) to graphical flourishes (DOT-based class hierarchy images) to minute details of processing (whether the first line of a block should be considered a summary).
It can generate everything from HTML to UNIX-style man pages to Eclipse help files.
5. Doxygen generates documentation faster
Perhaps it's shallow. Perhaps it's a false metric for this tool... but I like the fact that doxygen is just so incredibly fast. I like it that when I am writing and testing documentation, the process doesn't involve waiting for long periods of time while the documentation regenerates.
Conclusion
Notice that I haven't really criticized PhpDocumentor. I think it is a very good program, and I've used it with success on numerous projects. Better HTML templates and extended documentation would go a huge way toward leveling the playing field. But for my needs, Doxygen seems to be the best choice for PHP documentation.
I've posted on Doxygen before, but this is my well-considered view after using it for over a year on six different medium-to-large projects.
