If you've ever looked at your code an wondered about its commenting, if there was a kind of "best practice" to follow when it comes to its structure, you should read this article from Andrew Podner about docblocks.

The subject is how to properly document code with PHP comments and docblocks. This one took a while for me to really just accept as a part of the development process. To me now, the comments are now just as much a part of the application as the code is. I believe it is that important. With IDE's today, there really is no reason not to have good documentation in your source code.

He talks some about his own reluctance at first to use comments and how it helped him remember what his thought process was behind parts of this code. He includes an example of a typical docblock structure, showing the general description, parameters and a "return" value. He also includes something interesting in the topic of documentation - good variable names. There's links included to two tools that can take these standardized comments from your code and build HTML documentation from it - phpDocumentor and ApiGen.

You can find out more about the PHP docblock standards from this site.

Chris Hartjes, a big proponent of testing in the PHP community, has a new post to his blog about a new testing tool he's released to make it easier for you to know what needs testing - Tricorder.

I've hacked together a little CLI script that I think will be of use to many people who are trying to answer the question "just what should I do to test this thing anyway?" as they learn how to write PHPUnit tests to go along with their code. [...] I've created something that I am calling PHP-Tricorder, a CLI utility that can be used in conjunction with phpdoc structure.xml files to make suggestions on testing scenarios. It's at a 0.1 release right now, so I anticipate it will grow and add more features as time goes on.

The post includes an example of the output generated from the phpdoc's XML output, recommending things like:

• Mocking certain objects
• Testing for data types and contents
• Recommending testing ideas for private/protected methods

You can grab (or contribute to!) the latest version of the tool over on github.

Gonzalo Ayuso has a new post to his blog looking at a method for injecting dependencies into your application's code based on comments in the PHPDocumentor-formatted comments of your methods.

Last month I attended to Codemotion conference. I was listening to a talk about Java and I saw the "@inject" decorator. I must admit I switched off my mind from the conference and I started to take notes in my notebook. The idea is to implement something similar in PHP. It's a pity we don't have real decorators in PHP. I really miss them. We need to use PhpDoc. It's not the same than real decorators in other programming languages. That's my prototype. Let's go.

All of the code you'll need to recreate his solution is included - a sample "User" class that needs a valid PDO object in a private "db" property, a "DocInject" class that parses the comments and, using a new feature of PHP 5.4 (traits), injects the needed functionality into the "User" class and creates/assigns the object.

You can see just the full code in these two gists on Github.

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.

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.