(^60) CHAPTER 6 ■ DOCUMENTATION AND CODING CONVENTIONS
Ta b l e 6- 1. Common PHPDoc Tags
Tag Description
@access public|private|protected Describes the access level. This tag is not particularly
useful for use with reflection, as the API can determine
this ability automatically. In PHPDoc, it is used to allow
you to omit generating documentation for private
members.
@author Author Name
[[email protected]]
Helps determine who is responsible for a particular
element (I strongly recommend its use).
@copyright Copyright Information Allows you to specify the copyright of the code.
@deprecated [version information] Allows you to tell consumers of your code that an
element is no longer to be used and has been replaced.
@example [path|url] description Lets you reference an example of how to use the
element. The second parameter can be a path or
a full URL.
@filesource Allows you to indicate that you want to make the
source of the file available to the documentation.
This tag can be included only in a page-level block
and will be ignored elsewhere.
@global datatype description Describes the global variable data type. This tag
must immediately precede a global variable and is
applicable only to phpDocumentor-parsed docu-
mentation. It is not useful for reflection-based parsing.
@ignore Tells the parser to ignore an element and to not
include it in documentation.
@internal Allows you to hide certain information from public
documentation. It can be used in-line as well as on a
new line.
@license url [license] Specifies the URL to the license this software is used
under and optionally describes the license name.
@link url [description] Includes a link in your documentation. This tag may
be used in-line.
@param datatype $variablename[,.. .]
description
Describes the parameters associated with functions
and methods. This is probably the most important
tag. The variable name argument can optionally
include ,... to indicate there may be an unlimited
number of other parameters passed to the function.
This tag may appear multiple times in a block.
(See Listing 6-2 for examples.)
@return datatype description Describes the type of data returned by a function or
method. This is probably the second most important
tag and is the only way in PHP to include metadata
about the returned data. I recommend that you use
this tag with all functions that return a value.
McArthur_819-9C06.fm Page 60 Friday, February 22, 2008 8:59 AM
vip2019
(vip2019)
#1