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>
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...
*
* @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) {
...
}
} |