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.

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).

Michelangelo van Dam has posted the latest in his "quality assurance in PHP projects" series today with a look at something that can make your life and documentation easier - PHPDocumentor.

Unfortunately I've come across too many lines of code that were just lines of code, no comments or annotations provided. So, in best cases I could guess the types and parameters, but in many it was too obfuscated. I already talked about usage of a code sniffer like PHP_CodeSniffer in my previous post where you can validate the usage of comments in the code. But forcing developers (using a pre-commit checker) into writing documentation with their code is not really a good thing.

He suggests using something like PHPDocumetor (there's other PHPDoc parsers including DocBlox and Doxygen out there) to automatically generate documentation for your code based on its comments, giving your developers easier web-based access to the contents. He includes some sample docblocks for a class/method and gives an example command line call to build docs based on a project. A screencast and screenshot of the generated site shows the results of the run.

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.

In a new post to his blog Stefan Koopmanschap shows you how to get DocBlox installed for your documentation-generation needs as an alternative to phpDocumentor.

People using PHP that want API documentation usually automatically think of phpDocumentor, which used to be the de facto standard for generating API documentation from your PHP projects. However, the project has been dormant for a long time now and definitely does not support new PHP features such as namespaces, so it was really time to look for an alternative. In this blogpost, I'll show you how I set up my Jenkins CI to use DocBlox, one of the new API documentation generators currently available.

The DocBlox project is in active development and supports additional things in top of the current feature set phpDocumentor includes. Stefan gives you the exact XML you'll need to include in your Jenkins build file (and the phpDocumentor line it will likely replace) that builds out the documentation to a given path. He's given an example of his full build file to give you some context too.

Gonzalo Ayuso has a new post to his blog today talking about a regular expression-laden script he's some up with to reflect over a PHP file and pull out the document's comments (PHPDoc-style).

I want to parse PHPDoc code. Let me explain a little bit what I want to do. Imagine a dummy function documented with PHPDoc. [...] PHP has a great reflection API, but as at least in the current PHP version (as far as I know) we only can get the PHPDoc as a string, without parse it. I need to get the parameters and the type of them with reflection. [...] But the type is different.

His script (based loosely on a bit of a component from the Zend Framework) parses the file and its comments and grabs the variable types from the PHPDoc blocks on each method and associates them.

If you're looking for a more mature solution than just this script, take a look at Docblox, a PHP 5.3 documentation generator.

Frustrated with some of the limitations the phpDocumentor tool has - mostly dealing with the memory issues - Mike van Riel has introduced how own tool that works similar but takes better advantage of advancements in PHP to keep things bit more manageable - Docblox.

Right before or during the Dutch PHP Conference 2010 the issue had arisen again and this time I was determined on solving it. In the end I chose to build a new Documentation Generation Application (may I coin DGA?) for PHP [...] With [a list of key] requirements written down in a small TODO file I started designing the new project (which at the time was still nameless) After spending some hours designing, coding, prototyping, designing, coding and testing is now the time to reveal the fruits of my labour: DocBlox

Currently the project is in a pre-release state but is quickly headed to a 1.0 release. The current codebase is completely able to parse files and output the results to HTML files. PDF support is planned for the future. You can find the current feature list here and can download/clone the latest source from it's github repository.

Gonzalo Ayuso has a new post to his blog looking at some of the recent work he's done with PHPDoc and annotations to create "function decorators" in his code.

The idea is to solve the same problem I had when I wrote the previous article. I want to protect the execution of certain functions in a class to only being executed if the user is logged on. [...] The solution with interfaces is clean and simple (no extra libraries need and no reflection need too). The problem is that I can use it only for all the functions of the class.

He gives an example class with four different methods (one with annotations) and his annotation parsing class that runs the predispatch and postdispatch methods based on those annotations. He also shows another examples using an abstract class.

In a quick post to his blog Hasan Otuome points out an issue he had when running phpDocumentor on his application's codebase resulting in a broken end result.

Recently had to run PhpDocumentor on a project only to be faced with broken documentation after bringing all class files into compliance with proper comments. At first I thought I was missing a config flag for the command-line but, it turns out that the PhpDocumentor-1.4.3 ZIP download contains broken template elements.

He provides two screenshots showing the broken result of his run (wrong extensions mainly) and how he used this tool to correct the damage.