In this recent post to his blog Philip Norton shows you how to get started with DocBlox, the "new defacto PHP class documentation generator" that recently announced it would be merging with the phpDocumentor project in version 2.

Whereas PHPDocumentor would scan and generate all of the code in one go, DocBlox will scan the source code and generate a series of XML files based on the code it finds. It will then use these files to generate the API documentation in a number of different formats, although HTML is probably the most common.

He points out a few packages that you need to have installed before continuing (PHP-XSL, Graphiz, PEAR) and the commands you'll need to get it installed via the PEAR installer. He shows the commands to generate the documentation, how to install different template types and set up a configuration XML file.

As is mentioned in this new post to the DocBlox blog, there's been a major development between it and the phpDocumentor documentation generation tool - phpDocumentor 2 will be released soon, merging DocBlock and phpDocumentor into one tool!

Announcing phpDocumentor 2 - the merging of the old (phpDocumentor) and the new (DocBlox). With the first alpha release of phpDocumentor (2.0.0a1), the new "Responsive" default template sports a new page layout, along with the useful layout improvements that the original DocBlox templates provided (which remain available) over the old phpDocumentor templates (which will retire with old phpDocumentor). Explore this new template at http://demo.phpdoc.org/Responsive/index.html.

Users of the current phpDocumentor software (version 1.x) will need to upgrade their documentation and installations. If you'd like more information about the transition or just keep up with the latest on this exciting advancement, check out #phpdocumentor on Freenode IRC or follow @phpdocumentor on Twitter.

Michael Bodnarchuk passed along a new post on the Codeception site about using the tool in a behavior-driven testing methodology. This post is a follow up to their previous one covering acceptance testing.

With BDD approach in Codeception, any test, even the unit test, is written as a scenario. By this scenario you declare what you are doing and what results you expect to see. In traditional xUnit scheme your test is just a piece of code that uses the method being tested. This piece of code becomes a mess when you test complex units depending on other classes or when you need to check data in a database, etc. Codeception always keeps your unit tests simple and readable.

Sample code is included for a simple "User" model class that needs testing. Since the class only directly contains a "create" method, that's all they test - setting up a new user, calling "create" and checking to see if they exist. This basic test is modified slightly to handle the exceptions that might be thrown from the "create" method (when something happens like the user already exists) and checking the user's default role assertions. Plus, using this plugin for DocBlox, you can generate readable test documentation directly from the code.

Ben Selby has released a Sublime Text 2 plugin for the popular PHP-based documentation generation project DocBlox.

It seems that the editor of the moment is Sublime Text 2 and sadly I have to tip my hat to Gary Rockett for showing it off to me one day.. Since that day, I've been a 100% convert. [...] So, I decided to peak into the PHPUnit [plugin from Stuart Herbert] to see if I could create a DocBlox Plugin. It turns out you have to write Plugins in Python, which is interesting, since I know very little python. There seemed to be enough code there to get me going, so I now have a working DocBlox Plugin.

The result is a plugin that, once installed gives you a new context menu option to "Generate documentation" for the selected file. The console shows the progress of the build. You can get the plugin from Package Control or by grabbing it from github directly.

On PHPMaster.com today there's a new post from Moshe Teutsch about working with docblock comments in PHP scripts and how to use the phpDocumentor tool to generate the documentation from them.

If you've ever tried to read code written by someone other than yourself (who hasn't?), you know it can be a daunting task. [...] PhpDoc, short for PhpDocumentor, is a powerful tool that allows you to easily document your code via specially formatted comments. [...] By using PhpDoc, you can make it easy for others (and yourself) to understand your code - weeks, months, and even years after you've written it.

He introduces the concept of "docblocks" and includes several examples of how to comment things like packages, files, classes and functions/methods. Finally, he wraps up the post with an example of using the "phpdoc" command to run phpDocumentor and build the docs. In the comments, another tool is also suggested - DocBlox, a project that still parses the same docbloc syntax but does it in a much more memory efficient way (and is an actively maintained project).

On the Tales of a Coder blog there's a recent post about DocBlox, an alternative to the usual phpDocumentor for generating automatic documentation, and how it made it "pain free" for her current project.

Want to generate documentation for your PHP project, but keep putting it off? Can't be bothered wading thigh deep in documentation, screaming WHY WON'T IT WORK as you try to set it up? Look no further. DocBlox is pain free and you'll be up and running, literally in a few minutes.

She includes a guide to getting the latest DocBlox installed and configured to work with your project. The configuration is a straight-forward XML file, so changing the settings to match your needs is easy (more on the config here). Once this is configured, building your documentation is one command away. For more details on DocBlox, check out the project's website.

On DZone.com there's a recent post from Giorgio Sironi sharing his opinion on what should be your choice of automatic documentation generation tools in your PHP app, that 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, doxygen and DocBlox. 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.

He covers the installation of the tool (from its PEAR channel), some of the features it comes with, a link to their demo and some of his impressions after trying it out on his codebase.

As a follow up to his previous post about using DocBlock commenting and phpDocumentor for automatic project documentation generation, Michelangelo van Dam has posted a deeper look at DocBlox, one of his previously mentioned alternatives.

First of all, thank you all for the enormous feedback I got on my latest article on documentation of code. I got a lot of comments on the usage of PHPDocumentor. [...] I have to agree that [there are reasons] valid enough to step away from PHPDocumentor as a tool for documentation purposes and look for a better alternative. So I've investigated one tool most people have commented on or tweet-ed/facebook-ed/g+-ed on: DocBlox.

He touches on the installation of the tool and mentions this tutorial from Matthew Weier O'Phinney that guided him through the setup and use of DocBlox. He rand a few tests comparing phpDocumentor and DocBlox for the documentation generate and DocBlox came out on top when it came to runtime (and memory usage).

On his blog today Matthew Weier O'Phinney has a new post looking at an alternative to some of the other PHPDoc-based documentation tools, DocBlox, a tool written in PHP.

Until a few years ago, there were basically two tools you could use to generate API documentation in PHP: phpDocumentor and Doxygen. [...] phpDocumentor is practically unsupported at this time (though a small group of developers is working on a new version), and Doxygen has never had PHP as its primary concern. As such, a number of new projects are starting to emerge as replacements.

He introduces DocBlox as one of these alternatives and points out where you can get the latest version (from one of many sources including github, PEAR or by just grabbing a release. He includes instructions on how to run the tool on your code, use it to identify missing docblock comments and how to use the class diagrams feature that gives a more visual sense of how things fit together. He also mentions changing the title of the output, using different templates and how it uses a local SQLite database to cache the parsed information about your code (making it simpler and faster to do updates in the future).

On the Liip blog there's a new post that compares some of the popular PHPDocumentor-formatted comments parsers. They're looking specifically at the support for interfaces, not just the usual classes and methods.

The interfaces define the standard and are extensively documented. The implementation was built by copying the interfaces and implementing the methods. Now we have the documentation comments duplicated, which is a pain to maintain if we clarify or change anything in the interfaces documentation. [...] In PHP, there is a couple of doc compilers. While they basically all follow the same syntax as Java uses, none of them gets everything right unfortunately.

The four covered are PhpDoctor, DocBlox, PHPDoc and Doxygen. They look at things like namespace support, the inheritance information they generate and if it correctly uses the "@inheritDoc" tagging functionality.