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

Karsten Deubert has a recent post to his blog looking at annotations in Zend Framework applications to enhance functionality already in the framework.

Recently I had the idea to influence Controller Actions with annotations but discarded it with thoughts like "In PHP I will have to use reflection and some black magic to get this working which will have insane performance hits for my applications"... until I set everything up to see that it costs just 1-2ms in average per request without any form of caching.

He includes a few bits of code to show a simple annotation example (setting a layout) and the controller plugin that performs the translation. In his case, it's hard-coded to look for the "@layout" annotation in the docblock comment, but it'd be relatively trivial to extend it to a more full-featured version.

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 DevShed today there's a new tutorial showing you how to integrate Facebook commenting with your PHP application via the Facebook Connect API.

Facebook comments are a great way to optimize your site for social media and add a level of user-engagement to you site. Quality website comments can increase your website's credibility, as well as its traffic. This tutorial will teach you how to use Facebook's API Connect to integrate comment boxes on your website in a few simple steps, utilizing a little PHP and some elbow grease.

You'll need to set up an application for your PHP app to make the connection. This will give you the unique keys for your application that'll be used in setting up the commenting. By including a Facebook javascript file, all you'll need to do is output a special "fb" HTML tag with the right attributes and a meta tag or two to configure it with your application's keys.

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.

Francesco Montefoschi has a recent post to his blog looking at a tool you could use to ensure the quality of your code comments - PHPADD, the abandoned docblock detector.

PHPADD can analyze a directory with PHP source code and detect (for each file, for each class, for each method) if the parameters in the function declaration are compatible with the parameters found in the docblock, reporting the outdated ones. This can be easily integrated in your build script and the result can be published in build result. Using Hudson, you just need HTML Publisher plugin.

The include the (super simple) installation instructions for pulling it in via the PEAR installer and running it on your codebase. There's even some sample output included. If you're interested in the source, check out (or fork) the latest code on github.

Aleksey Martynov has submitted a project that can come in quite handy of you do a lot of work with XML in your application - a XML serialization tool for PHP 5.3 that lets you easily translate objects into valid XML.

lexa-xml-serialization is a lightweight library for serializing PHP objects to XML like it's done in .NET. My xml serializer requires that you mark serializable properties of your classes with doc-comment annotations. The properties are not required to be public. The lettercase of annotations doesn't matter. Whitespaces are not essential. Parameters are optional: type defaults to string, xmlName defaults to the property name. Parameter values must not be enclosed in quotes. Empty brackets may be omitted.

The page on the Google Code site gives some examples of it in use as well as as "first look" tutorial about building a large, more complex XML file. If you want to try it out, head over to the download page to grab the latest.

Abhinav Singh has a new post today looking at his method for preventing duplicate comments (similar to a method used on Wordpress blogs) using memcached.

In this blog post, I will put up some sample PHP code for Duplicate comment detection using Memcached without touching the databases. Towards the end, I will also discuss how the script can be modified for usage in any environment including forums and social networking websites.

His method uses a custom function (is_repetitive_comment) to create an md5 hash of the comment and username to check against the stored values on the memcached server. Code is included as is an explaination of how it all works together.

Jani Hartikainen has posted some of his opinions about code commenting in a response to this post from James Carr claiming that code comments on fresh code is a bad idea.

James puts it quite well: When you write comments, it would be much better idea to just talk with your coworkers about it. He uses "excuses" as an example - code which does something that you need to explain, or says something like "Here we do X but we should really do Y" While I partially agree - if you're not sure which approach you should use, or whether your approach is correct, talking with your coworkers is definitely a good idea.

Jani talks a bit about what he considers good and bad commenting - non-redundant, descriptive and sometimes difficult to remember to do correctly.