Section B.3. Tag Reference

B.3. Tag Reference

Some of the keywords mention "Available for PHP 4 only." This does not mean that you cannot document this type of element in PHP 5; instead, phpDocumentor extracts this information from the source so that you don't have to mark it explicitly with a keyword.

B.3.1. abstract

Available for PHP 4 only.

Syntax:

 @abstract 

The abstract keyword documents an abstract class or member function, or variable that should be implemented by the class that extends this one. A good example of an abstract class is a container class, and an example of an abstract function might be an output function of a generator. An abstract class or function itself usually does not implement any kind of functionality, but it might contain fallback routines:

 /** * Example class to show @abstract * * Abstract class to add two elements * * @author Derick Rethans <[e-mail]> * @abstract */ class Sum {     /**     * Sum function     *     * This function adds two elements and stores the result     *     * @abstract     * @param mixed $e1  The first element     * @param mixed $e2  The second element     */     function Sum ($e1, $e2) {         ;     } } /** * Example inherited class * * Add two arrays */ class SumArray extends Sum {     /**     * Add two arrays     *     * @param array $a1  The first array     * @param array $a2  The second array     */     function Sum ($a1, $a2) {         return array_merge($a1, $a2);     } } 

B.3.2. access

Available for PHP 4 only.

Syntax:

 @access <accesstype> accesstype :== 'private' | 'protected' | 'public' 

The @access keyword marks an element as either public, protected, or private. Private elements are for internal use, and do not belong in the user documentation. phpDocumentor will only output private elements when pp is passed on the command line. The default access method of elements is public, thus, this tag is only required when you want to mark an element as private. Following the PEAR coding standards, private functions and variables should have an underscore as a prefix to the symbol name.

 /** * Example class to show the use of the access tag */ class Example {     /**     * @var    float $_amount   Amount of money in my pocket     * @access private     */     var $_amount;     /**     * Subtracts money from my pocket and gives it away     *     * @param  float $money   Amount of money to give away     * @access private     */     function _giveMoneyAway ($money) {         $ret = $this->_amount;         $this->_amount -= $money;         return $ret;     }     /**     * Calculate the amount of money and give it away     *     * @param  int $bills   Number of ¤10 bills to give away     * @access public     */     function giveBillsAway ($bills) {         return $this->_giveMoneyAway($bills * 10);     } } 

B.3.3. author

Syntax:

 @author <name> '<' <email-address> '>' 

The author keyword documents the author of an element:

 /** * Super-duper resource management class * * @author  Derick Rethans <[e-mail]> */ class ResourceManager { } 

B.3.4. category

Syntax:

 @category <categoryname> 

This tag puts a specific class into a category. This is most useful for documenting PEAR classes, which are always in a category like Database, HTTP, or XML. For example, see this header from XML/Parser.php:

 /**  * XML Parser class.  This is an XML parser based on PHP's "xml" extension,  * based on the bundled expat library.  *  * @category XML  * @package XML_Parser ... 

B.3.5. copyright

Syntax:

 @copyright <copyright_information> 

With the @copyright keyword, you can document copyright information. Although it is mostly used for whole files, you can also document the copyright information of a single function or class:

 /** * Copyright example * @author Derick Rethans <[e-mail]> * @copyright Copyright © 2002, Derick Rethans */ /** * Loaned function * @copyright Copyright © 2004, the PHP Group */ function crash_computer() { } 

B.3.6. deprecated

Syntax:

 @deprecated <description> 

To document obsolete functions, use the @deprecated keyword. The parameter to this keyword will be copied verbatim to the generated documentation. It's most useful to use this parameter to document when, and from which version of the application or script the documented element is deprecated:

 /** * @deprecated Removed in version 0.8.1.2 */ function add_all_arrays() { } 

B.3.7. example

Syntax:

 @example <path/to/example.php> <description> 

Examples of using specific classes can be put in the documentation in different ways. With <code>, you can do it inline:

 /**  * This function is an example  * <code>  * example_function("example_var");  * </code>  */ function example_function($var) { } 

But, you can also link in an example from a file, like this:

 /**  * This function is another example  * @example example_example.php  */ function example_function($var) { } 

This will make phpDocumentor look in the directory that is specified with the -ed para-meter on the command line for the file example_example.php. If this file does not exist, phpDocumentor first looks for this file in the examples subdirectory of the current directory in which the documented file resides. If that also fails, it checks for the file example_example.php in the subdirectory "examples" of the top-level directory of the parsed files.

B.3.8. filesource

Syntax:

 @filesource 

This tag makes phpDocumentor generate a syntax-highlighted version of the file being parsed and linked to from the documentation. The command line parameter -s on will be automatically performed for every source file:

 <?php /** * @author Derick Rethans <[e-mail]> * @filesource * @package Examples */ /** * This class has automatic version numbers * @version $Id: version.php,v 1.4 2002/07/25 16:42:48 Derick exp $ * @package Examples */ class source_foo { } ?> 

B.3.9. final

Available for PHP 4 only.

Syntax:

 @final 

Use the @final keyword to document that the class or property should not be overloaded. (See it as the final node in an inheritance chain.)

 /** * Top level class * @abstract */ class top { } /** * Middle layer class */ class middle extends top { } /** * Bottom layer class * @final */ class bottom extends middle { } 

B.3.10. global

Syntax:

 @global  (type | object_definition)  <$variable>  <description> type              ::=  php_type | 'mixed' php_type          ::= 'bool' | 'int' | 'float' | 'string' | 'array' | 'resource' object_definition ::= 'object' <classname> 

The @global tag has two functions. The first one is available with both PHPDoc and phpDocumentor, and documents the use of a global variable in a function or method. The second one is only available in phpDocumentor and documents global variables for the whole script (a top-level variable). Either of those functions are showed in a different example:

 /** * This function rewinds the directory */ function rewindDir() {     /**     * Global variable which holds the directory object to rewind     * @global object Dir $dir   Instance of the directory class     */     global $dir;     $dir->rewind(); } /** * Example to document a global variable * @global string $GLOBALS['foo'] * @name foo */ $GLOBALS['foo'] = "Foobar"; 

The variable name after the @global keyword should be exactly the same one as below the comment. This includes the quotes! You can also "rename" the documented variables with the @name tag. See the documentation on the @name tag for more information.

B.3.11. ignore

Syntax:

 @ignore 

This keyword is meant to exclude certain elements from the documentation. An example usage follows:

 if (version_compare(phpversion(), "4.3.0", "<")) {     /**      * @name BROKEN_PHP      */     define("BROKEN_PHP", TRUE); } else {     /**      * @ignore      */     define("BROKEN_PHP", FALSE); } 

Without the @ignore tag, the element would have been included twice in the documentation.

B.3.12. inheritdoc (inline)

Syntax:

 {@inheritdoc} 

B.3.13. internal, internal (inline)

Syntax:

 @internal <description> 

or

 {@internal <description> }} 

Use this tag to document something not interesting for the public (for example, for in-company documentation). An example is

 /**  * Class to modify files  *  * With this class you can easily modify existing files on your system.  * {@internal The way this class does this is kinda stupid though... }}  */ 

Another one not using the inline version of @internal:

 /**  * Class to modify files  *  * With this class you can easily modify existing files on your system.  * @internal The this class does this is kinda stupid though.  */ 

It doesn't really matter which one you pick because the rendering to the documentation is the same. If you want to have this shown in the generated documentation, you'll have to specify the -pp option (just as you do when showing private methods).

B.3.14. licence

Syntax:

 @licence <url> ( <description> ) 

This keyword makes a link to url with an optional description description:

 /**  * @package Examples  * @licence http://www.php.net/licence/3_0.txt PHP License  */ 

B.3.15. link

Syntax:

 @link <url> ( <description> ) 

This keyword adds a link into the generated documentation. You can use this to make a link to an example on how to use this element. (For an example, see link (internal).)

B.3.16. link (inline)

Syntax:

 {@link <url> <description>} 

or

 {@link <element> <description>} 

The {@link} inline tag makes links to either a URL or another documented element by placing a link in the flow of the text. See the following examples:

 /**  * Page level docblock for link test  * @package Examples  */ /**  * Function link_foo1  *  * The following adds a link at the end of the description block.  * @link http://www.example.com example link  */ function link_foo1() { } /**  * Function link_foo2  *  * This is a {@link foo1() link to foo1}, inline rendered in the  * documentation.  */ function link_foo2() { } 

B.3.17. name

Syntax:

 @name <global_variable_name> 

This keyword gives a pretty name to a global variable. In the next example, $foo is used in the generated documentation instead of $GLOBALS['foo']:

 /** * Example to document a global variable * @name $foo * @global string $GLOBALS['foo'] */ $GLOBALS['foo'] = "Foobar"; 

B.3.18. package

Syntax:

 @package <modulename> 

The @package tag is the tag used for grouping elements (and subpackages with phpDocumentor). It's the top-level grouping item and usually associated with a PEAR package. See the example shown in Figure B.1, which uses the package and subpackage tags to document functions in a structure with two levels from the following structure.

 /** * Cache management * @package Cache */ function Cache() { } /** * Caching in a database * @package Cache * @subpackage Cache_DB */ function Cache_DB() { } /** * Caching in a MySQL database * @package Cache * @subpackage Cache_DB */ function Cache_DB_MySQL() { } /** * Caching in an Oracle database * @package Cache * @subpackage Cache_DB */ function Cache_DB_Oracle() { } /** * Caching in a file * @package Cache * @subpackage Cache_File */ function Cache_File() { } 

Figure B.1. Package structure.

B.3.19. param

Syntax:

 @param  (type | object_definition)  <$variable>  <description> type              ::=  php_type | 'mixed' php_type          ::= 'bool' | 'int' | 'float' | 'string' | 'array' | 'resource' object_definition ::= 'object' <classname> 

Parameters to functions are documented with the @param tag.

Some examples follow:

 /** * Function to add numbers and multiple by two * @param float $a  This is the first element that's going *                  to be in the result * @param int   $b  And here we have the second parameter * @return mixed */ function addNumbersAndMultiplyByTwo ($a, $b) {     return ($a + $b) * 2; } 

phpDocumentor detects the default value of a variable from the source, and includes this automatically in the generated documentation. A more complex example follows:

 /** * Return rows * * Run a query on the database connection and return the specified number * of rows if specified * @private * @param resource $conn  The database connection resource * @param string   $query The query * @param int      $limit Limit to this number of returned rows * @return array */ function _runQuery ($conn, $query, $limit = 0) {     $ret = array();     mysql_query ($conn, $query . ($limit ? " LIMIT $limit" : ""));     while ($row = $mysql_fetch_row) {         $ret[] = $row;     }     return $ret; } 

B.3.20. return

Syntax:

 @return (type | object_definition) <description> type              ::=  php_type | 'mixed' php_type          ::= 'bool' | 'int' | 'float' | 'string' | 'array' | 'resource' object_definition ::= 'object' <classname> 

Use the @return tag to document the return type of your function:

 /** * @param  string    $filename   The filename of the image * @return resource              A GD image resource */ function returnNiceGif ($filename) {     return imagecreatefromgif ($filename); } 

B.3.21. see

Syntax:

 @see <element> 

With the @see tag, you can add links to other elements in the documentation. Every phpDocumentor element type is supported as parameter to the @see tag:

 /** * Adds numbers * @see string::add() */ function addNumbers ($number1, $number2) {     return $number1 + $number2; } /** * String manupulation class */ class string {     /**     * Adds strings     * @see addNumbers     */     function add ($string1, $string2)     {         return $string1 . $string2;     } } 

B.3.22. since

Syntax:

 @since <description> 

This tag documents when an element was added to the API. The format of the description string is free. Here is an example from the PEAR class HTML_Common:

 /**  * Returns the tabOffset  *  * @since     1.5  * @return    void  */ function getTabOffset() {     return $this->_tabOffset; } 

B.3.23. static

Available for PHP 4 only.

Syntax:

 @static 

This tag documents that methods may be statically called (like Foo::Bar(); ):

 /** * Class foo that does static bar */ class foo {     /**     * This function may be called statically     * @static     */     function bar () {     } } foo::bar(); 

B.3.24. staticvar

Available for PHP 4 only.

Syntax:

 @staticvar  (type | object_definition)  <$variable>  <description> type              ::=  php_type | 'mixed' php_type          ::= 'bool' | 'int' | 'float' | 'string' | 'array' | 'resource' object_definition ::= 'object' <classname> 

The @staticvar tag documents a static variable within a function. Static variables are not destroyed when the function ends. The following example will print 123:

 /** * Example for static variable in a function * @staticvar  integer $count  Count the number of times this function was called. */ function foo() {     static $count;     $count++;     echo $count. "\n"; } foo(); foo(); foo(): 

Here's the output:

 1 2 3 

B.3.25. subpackage

Syntax:

 @subpackage <subpackagename> 

A subpackage can be used as an additional grouping layer for elements in your package. See the description of the package tag for an example.

B.3.26. todo

Syntax:

 @todo <description> 

With the @todo tag, you can document changes that still need to be made to a specific element. Here's an example:

 /**  * @todo Document parameters  */ function todo_example($a, $b) { } 

B.3.27. uses

Syntax:

 @uses <element> 

This tag does the same as the @see tag, except that it makes a two-way link between the "used" element and the element from which @uses is used. phpDocumentor does this by adding a pseudo pseudo tag @usedby to the element to which the @uses tag points. Here's a small example to illustrate this:

 /**  * This function multiples  * @param int a  * @param int b  * @uses divide()  */ function multiply($a, $b) {     return divide($a, 1 / $b); } /**  * This function divides  * @param int a  * @param int b  */ function divide ($a, $b) {     return $a / $b; } 

This example makes a link from multiply to divide and from divide to multiply.

B.3.28. var

Syntax:

 @var  (type | object_definition)  <$variable>  <description> type              ::=  php_type | 'mixed' php_type          ::= 'bool' | 'int' | 'float' | 'string' | 'array' | 'resource' object_definition ::= 'object' <classname> 

var documents the type of class variables. The type should be a valid PHP data type, or "mixed" if the variable can have different types:

 /** * Class that 'emulates' a structure as in C */ class person {     /**     * @var string $name The name of the person     */     var $name;     /**     * @var int $age   The person's age     */     var $age; } 

B.3.29. version

Syntax:

 @version <description> 

The version of the element may be documented with this tag. If you use CVS, you can use the CVS tags $Id: $ and/or $Revision: $, which are automatically replaced with the correct version when you check your source in the CVS tree.

 /** * This class has automatic version numbers * @version $Id: version.php,v 1.4 2002/07/25 16:42:48 Derick exp $ * @author Derick Rethans <[e-mail]> */ class foo { }