Doc comments

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.

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

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.

Note: 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:

But take care, this tags maybe ignored by non-html PHPDoc renderer.

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