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.
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:
<a>
<i>
<b>
<pre>
<ul>
<li>
<br>
<code>
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) { ... } }
Deliver First Class Web Sites: 101 Essential Checklists Want to learn how to make your web sites usable and accessible? Want to ensure that your sites meet current best practice, without spending hours trawling through incomprehensible specifications and recommendations from dozens of different books, research papers, and web sites? Want to make sure that the sites you build are "right the first time," requiring no costly redevelopments?
Free Sample Chapters