Are you the kind of person who hates documenting your sourcecode? Does the thought of writing API documentation make your eyeballscontract and your toes itch? Well, itch no more - this articledemonstrates how you can use PHPDoc to automatically generate APIdocumentation using the comments in your source code.
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.
/ 14 
