There's no reason not to switch to DocBlox
- phpDocumentor is based on PHP 4, and not developed anymore (the last release was in 2008). It's the good old phpdoc command.
- DocBlox is a PHP 5.3 compliant, actively developed tool. It's already used in Zend Framework and Agavi. It was ceated by Mike Van Riel, a Dutch PHP developer whom I met at the last DPC where he held a DocBlox talk at the Uncon.
A PHP tool, faster than doxygen in implementing new features, and actively developed: these are the factors that made me choose DocBlox as my new default Api documentation mean.
The requirements for DocBlox are PHP 5.3 with the XSL extension enabled. Additional extensions will be required for additional functionalities such as graphs.
sudo apt-get install php5-xsl # in Debian-based Linux distributions sudo pear channel-discover pear.docblox-project.org sudo pear channel-discover pear.michelf.com # some dependencies sudo pear install docblox/DocBlox-beta
At the time of this writing, DocBlox 0.13.3 will be installed by these commands.
Features (from the docs)
Performance is one key advantage of DocBlox. It parses Zend Framework (version 1.1 in this benchmark) in less than 90 seconds; it has low memory usage (< 50 MB) and implements incremental parsing by only accessing changed files since the last execution. On a small-sized project, it's blazingly fast.
DocBlox has PHP 5.3 support: namespaces are recognized; scopes and other PHP 5 constructs are a default.
DocBlox own's demo shows how it has an user experience more advanced and current than phpDocumentor's old earthli template.
You can also see an example on real code, by taking a look at Zend Framework's Api documentation.
Trying it out
mkdir apidocs docblox run -d . -t apidocs
For the basic use case, that's it: parse the current folder by selecting only the PHP files and produce a result in the apidocs/ folder.
You can save the command in a Phing target, or introduce a docblox.dist.xml file to store the configuration:
<?xml version="1.0" encoding="UTF-8" ?> <docblox> <parser> <target>apidocs</target> </parser> <transformer> <target>apidocs</target> </transformer> <files> <directory>.</directory> </files> </docblox>
With this file in place, you can just run docblox in the folder containing it.
The default theme, which by the way will be the one used by the majority of the projects, is usable enough and good-looking. It shows:
- a list of classes and files on the left.
- C/I icons of different colors for classes and interfaces.
- p/m icons for property and methods.
- Circles of different colors (green to red) for scope private to public.
Wthout any docblocks present, DocBlox list methods organized by logic and physical location (class and file), their names and parameters.
With docblocks present, all metadata are extracted: fields are listed with type and default value; methods with their entire prototype (parameters with type and default if applicable, and return type of the method itself):The interface has foldable descriptions for methods in order to save space; the same classes for a package are listed in a single page loaded in the frame and are navigated via anchors, speeding up loading time. However I see from Zend Framework documentation that this behavior can be modified to break up classes in different pages.
There's no reason not to choose docblox as the default for your project and abandoning phpDocumentor. It is still a PHP-dedicated tool, written in PHP and distributed with an open source MIT license.
The docblocks tags supported are exactly the same, so the only thing that changes is the command for generation; the support is even improved as namespaces are correctly identified. Installation is available via PEAR and easier as for phpDocumentor, both for your development machines and for your Continuous Integration server.
DocBlox's documentation (it's documentation on the tool, not on docblock's syntax.)