Writing Self-Documenting PHP Code - Different Strokes
( Page 6 of 7 )

Now, while PHPDoc is a fairly cool little utility, it does come with some caveats. For one, the software is still in beta, and the author specifically notes that it may not work as advertised in all cases. Further, since the package is still under development, it's quite possible that there may be changes in future versions which are not backward-compatible. And finally, the program encounters difficulties if you include more than one class per PHP file.

If none of these things bothers you much, you should go ahead and begin using it. If, on the other hand, you're looking for alternatives, take a look at eZ phpdoc, a Perl-based auto-documentation utility created by the nice guys at eZ Systems (http://developer.ez.no).

I'm not going to get into the details of eZ phpdoc's syntax - there's a very good tutorial written by the author on that very topic at http://publish.ez.no/article/articleprint/29/ - but I will demonstrate a small example. Take a look:

<?php

//!! SandwichMaker
//! This class claims to make a sandwich for you automatically /*!
  One of the coolest inventions on the planet. class.Sandwichmaker
allows you to specify your bread and filling, and then makes a plate of
sandwiches matching your request. Ain't PHP cool? */

class SandwichMaker
{
	/// bread type	
	var $type;
	
	/// sandwich filling
	var $fillings = array();


	/*! 
	This function creates a sandwich with specified bread type and
filling
	*/
	function makeSandwich()
	{
		// snip
	}	

	/*! 
	This function sets bread type for sandwich
	*/
	function setType($type)
	{
		// snip	
	}
	
	/*! 
	This function sets filling for sandwich
	*/
	function setFillings($fillings)
	{
		// snip	
	}
	
}

?>

As you can see, the syntax used by eZ phpdoc is different from that used by PHPDoc. Some users seem to find it easier; personally, though, I prefer the PHPDoc way of doing things. You should try both to see which one you're more comfortable with.

Once you've got your code all commented, you can use the eZ phpdoc Perl script to generate some documentation for it.

$ ./ezphpdoc-1.0.pl /usr/local/apache/htdocs/classes/ -o /tmp/docs/

Here's what it looks like:



Note that eZ phpdoc can currently output documentation in HTML, LaTeX and Unix manual formats.

>>> More PHP Articles          >>> More By Harish Kamath, (c) Melonfire