There's no reason not to switch to DocBlox

Alessandro Nadalin signals these three options for Api documentation generation, the process of extracting Api informations on classes and methods from a folder full of source code:

• phpDocumentor is based on PHP 4, and not developed anymore (the last release was in 2008). It's the good old phpdoc command.
• doxygen is a mature choice that supports many languages, and it's not written in PHP (with some hacks it supports even JavaScript.)
• 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.

Installation

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.

The user interface produced by DocBlox contains a JavaScript search, and allows for independent theming and templating: multiple skins and multiple layouts. It has a support for a custom Writer implementations to transform the XML parsed structure in something other than HTML.

Demo

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.

User interface

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.

JavaScript navigation works even when not served from an HTTP server but just as a folder loaded in the browser. However JavaScript search requires the Api docs to be loaded via HTTP from a PHP-capable web server (a virtual host in your local Apache configuration will do it.)

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.

Conclusions

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 on GitHub

DocBlox's documentation (it's documentation on the tool, not on docblock's syntax.)