How To Document Your PHP Classes Page 3

I decided to test this script on its own PHP source and I found it working partially: it could just generate the
documentation of the classes (neatly formatted), but not the summaries. I don’t know if this happens just on my
machine, but it just stopped with a core dump (PHP 4.0 pl2 on a RedHat 6.2) when trying to generate the summaries.
Supposing you’ve a PHP executable installed in /usr/local/bin the syntax for calling it is (to have some results
I had to give full paths of both the php files and the output directory)

./phpautodoc <php_files> -o <output_dir>

phpdoc is a tool to maintain documentation about PHP files
on the web and it is best suited for distributed development efforts. The documentation gets written into a
MySQL database; after installing it you can document your classes by adding them using a web interface. This
is really interesting but is a way to maintain a low level documentation separatated from source code which
as I said it’s not very convenient.

A General Purpose Tool

After experiencing some frustration trying all these tools without much success and until a standard solution is
proposed by the Pear Project, I found a working tool completely
unrelated to PHP in the Open Source Projects at Apple website. The
name of the project is HeaderDoc. As the website
states HeaderDoc is a tool for generating HTML reference documentation for comments of C or C++ header files.
It is written in Perl for easy portability. Similar to JavaDoc, it allows developers to easily document their
interfaces and export that information into HTML.

Yes, you’ve read well, HeaderDoc supports just C and C++. No other languages, but it happens that, unlike
Javadoc, it relies mostly on tags written inside comments and so can works well for PHP too with minor
modifications (I will explain later). The tags are Javadoc-like, some examples of Headerdoc tags are
@class, @function and @var.

Documenting A Class

Ok so let’s dive into details now. First let’s take a look to how a class can be documented.

/*! @class BagItem
    @abstract An item in the shopping bag - it is a shopitem with quantity
    @discussion A BagItem object may be constructed without previous instantiation 
	of neither ShopItem nor Product
*/

Documentation of a class. On the left frame it is possible to choose a method of the class.

The first thing to notice is that the style used to open comments is not exactly like Javadoc comments
/** (a slash and two asterisks), but is instead /*! (a slash, an asterisk
and an exclamation mark). Tags are different too, but they work in a similar way.
For example the first tag is the @class tag which is used to document a class,
this tag is followed by the class name. The next tag is the @abstract tag which is
an optional tag describing in a few words the meaning of the class, while the @discussion
tag is another optional tag used for a more in depth discussion. Of course it’s up
to you to decide wether to write everything in the @discussion tag or use the
@abstract too, but remember that in general, the more specific tags
you use, the better the results are.