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.

Замечание: 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.


* Basket class for my web shop.
* Basket is a repository for instances of
* the class Article...
* @autor Alexander Merz <>;
* @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) {