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 <[email protected]>; * @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) { ... } } |