Doc comments --
the structure of a doc comment
The format of a doc comment
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.
<?php
/**
* 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
Short description part
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.
Замечание:
A 'line' means everything between the leading *-
character and a newline character.
Detailed description part
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.
Keyword part
The format of a keyword line is simple
<?php
* @keyword <parameters>
?>
|
Not every keyword is allowed for every element. See the scope
section where a keyword is permitted and where not.
Example
<?php
/**
* Basket class for my web shop.
*
* Basket is a repository for instances of
* the class Article...
*
* @autor 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) {
...
}
}
?>
|
|