Agile Zone is brought to you in partnership with:

I am a programmer and architect (the kind that writes code) with a focus on testing and open source; I maintain the PHPUnit_Selenium project. I believe programming is one of the hardest and most beautiful jobs in the world. Giorgio is a DZone MVB and is not an employee of DZone and has posted 636 posts at DZone. You can read more from them at their website. View Full User Profile

There's no reason not to switch to DocBlox

08.30.2011
| 8813 views |
  • submit to reddit
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.)

Published at DZone with permission of Giorgio Sironi, author and DZone MVB.

(Note: Opinions expressed in this article and its replies are the opinions of their respective authors and not those of DZone, Inc.)

Comments

Filip Procházka replied on Tue, 2011/08/30 - 9:00am

That's ugly generator... I mean it. It's ugly. Have a look at http://apigen.org/ It's way better.

Mario T. replied on Wed, 2011/08/31 - 12:51am

The generated manual pages definitely look nice, it's speedy and verbose when generating them. As far as CLI interfaces go it's also easy to use.   

However having the frigging top-level namespace separators in the generated class diagrams even if you don't actually use any is a little turn off. Not sure if this is configurable, or how to add basic support for @magic methods. But maybe it'll mature some more..

Mike Van Riel replied on Thu, 2011/09/01 - 11:57pm in response to: Mario T.

Hi Mario, I have not heard about the separators in class diagrams being annoying before, I will look into that. You can define magic methods and properties using the @method and @property tags. I am not familiair with @magic and can't seem to find a reference in the phpDocumentor docs?

Emma Watson replied on Fri, 2012/03/30 - 3:16am

 

Key advantages of the DocBlox are wonderful. Performance is the most admirable. In lesser than 90 seconds, Zend Framework is parsed. For smaller projects, it works efficiently and effectively.


 PHP 3.5 support is incredible. Independant templating as well as theming is possible by the JavaScript search of DocBlox.

java program

Comment viewing options

Select your preferred way to display the comments and click "Save settings" to activate your changes.