|
Sont indiqués en gras les éléments dont vous devez absolument vous servir... La syntaxe est propre à chaque marqueur. Cela n'est pas à connaître par coeur mais vous devez vous y référer à chaque fois que vous codez. |
The general format of a doc comment is independent of the element to describe. Make sure that there is nothing between the comment and the element, except blank lines.
/** * Short description - one line * * Detailed description (optional) * over several lines, the blank lines * between the description parts are * not necessary * * @keyword parameters_of_keyword * @keyword the sequence of keywords arbitrary */ [element to describe] |
Types of elements
class
function
var
define
include/require
This line should describe what an element contains or does. Example for a variable: "Count of articles", for a function: "Creates a hyperlink" or for a class: "provides PDF-related functions". This line will normally be rendered in an index page or table of content.
Note: A 'line' means everything between the leading *- character and a newline character.
In this part, you can write more about your element. Please note that parameters, return values and relationships between elements a covered by the keyword section. Some HTML-tags are allowed here:
<a>
<i>
<b>
<pre>
<ul>
<li>
<br>
<code>
But take care, this tags maybe ignored by non-html PHPDoc renderer.
The format of a keyword line is simple
* @keyword <parameters> |
Not every keyword is allowed for every element. See the scope section where a keyword is permitted and where not.
/**
* Basket class for my web shop.
*
* Basket is a repository for instances of
* the class Article...
*
* @author Alexander Merz <alexander.merz@php.net>
* @version 1.6
* @access public
* @package MyWebShop
*/
class Basket {
/**
* contains the articles
* @var array
* @see add(), mod(), del()
*/
var $articles = array() ;
/**
* Adds an article.
*
* An instance of the given article and the count is
* stored in the basket
*
* @param object Article $article article to add
* @param integer $count count of the article
* @return boolean returns false, if error occurs
* @access public
* @see $articles
*/
function add( $article, $count = 1) {
...
}
} |
@author -- describes the author
@author { Name } [ <email> ]
class
function
var
define
... * @author The invisible man * @author Alexander Merz <alexmerz@php.net> ... |
@const -- describes constants created with define()
@const { label } [ description ]
define
...
/**
* maximum of permitted clients at the same time
* @const MAX_CLIENTS maximum clients
*/
define("MAX_CLIENTS", 1000, true);
/**
* maximum request per client
* @const MAX_REQUESTS_PER_CLIENT
*/
define("MAX_REQUESTS_PER_CLIENT", 5);
... |
@deprecated -- markup outdated API elements
@deprecated { label }
class
function
var
define
Note that the format of label is not defined by PHPDoc.
... * @deprecated Rev. 1.8 - 03/10/2001 ... * @deprecated 03-10-2001 ... |
@global -- document global used variables
@global { type|objectdef } { $varname } [ description ]
function
...
* @global array $files list of file
* @global integer $errcode errorcode
* @global string $errmsg error message
* @global object FileSystem $fs instance of the FS class
*/
function fooBar() {
global $files, $errcode, $errmsg, $fs;
... |
@package -- group classes
@package { label }
class
... * @package Net ... |
@param -- describes a parameter of a function
@param { type|objectdefinition } { $varname } [ description ]
function
PHPDoc detects default values and document them from source.
...
* @param string $name name of the person
* (complete name!)
* @param integer $age age of the person
* @param float $size size of person
* @param object Adresse $adr adresse of the person
* @param array $childs names of the children
* @param boolean $job if true, person has a job
* @param boolean $gender use FEMALE
* or MALE
*/
function person($name, $age, $size, $adr, $childs, $job=true, $gender=FEMALE) {
... |
@see -- mark up reference to other elements
@see { element }
class
function
var
define
... * @see $article, Article::edit() * @see delete(), print() ... |
@since -- mark up the time as an API elements was introduced
@since { label }
class
function
var
define
Note that the format of label is not defined by PHPDoc.
... * @since Rev. 1.8 - 03/10/2001 ... * @since 03-10-2001 ... |
@static -- marks a function as static
@static
function
...
class Foo {
/**
...
* @static
*/
function Bar (...
...
// this call is permitted according to the docs:
Foo::Bar() ; |
@var -- describes class variables
@var { type|objectdefinition } { $varname } [ description ]
var
If no type is given, PHPDoc tries to guess.
... * @var string $name name of the person */ var name = "" ; ... |
PEAR : http://pear.php.net/manual/en/packages.phpdoc.php
The end!