PHPBuilder - How To Document Your PHP Classes Page 3



RSS Twitter
Articles Code Documentation

How To Document Your PHP Classes - Page 3

by: Stefano Locati
|
August 25, 2000

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

« Previous Page
1
|
2
|
3
|
4
|
5
Next Page »

Comment and Contribute

Your comment has been submitted and is pending approval.

Author:
Stefano Locati

Comment:



Comment:

(Maximum characters: 1200). You have characters left.