O'Reilly logo

PHP Cookbook by Adam Trachtenberg, David Sklar

Stay ahead with the world's most comprehensive technology and business learning platform.

With Safari, you learn the way you learn best. Get unlimited access to videos, live online training, learning paths, books, tutorials, and more.

Start Free Trial

No credit card required

21.8. Documenting Classes with PHPDoc

Problem

You want to be able to integrate documentation with your code.

Solution

Use PHPDoc. This allows PEAR to accurately list your class, and you can use the PHPDoc tools to automatically generate API documentation in HTML and XML.

PHPDoc syntax is based on Javadoc. The following tags are available for use: @access , @author, @package, @param, @return, @since, @var, and @version.

You can then use PEAR’s PHPDoc utility to generate documentation.

Discussion

PHPDoc has a special inline documentation style. By formatting your comments in a particular way, the PHPDoc script can parse your code to not only generate which parameters a function take and what type of variable it returns, but also associate comments and other useful information with objects, functions, and variables.

PHPDoc comments are based on the same formatting and naming conventions as Javadoc. So, to flag a comment block to grab PHPDoc’s attention, use a traditional C-style comment but use two asterisks after the opening slash:

/**
* This is a PHPDoc comment block
*/

Inside of a block, certain keywords have special meaning. These keywords all begin with an at sign. Table 21-2 lists the keywords and what they stand for.

Table 21-2. PHPDoc keywords

Keyword

Meaning

@access

Method access: public or private

@author

Package author

@package

Package name

@param

Function parameter

@return

Function return value

@see

See also reference

@since

Debut version ...

With Safari, you learn the way you learn best. Get unlimited access to videos, live online training, learning paths, books, interactive tutorials, and more.

Start Free Trial

No credit card required