Doc comments

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.

/** * 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.

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>

Keyword part

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.

Example

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