Writing Documentation

Documenting a class

Using the file, for example: protected/modules/contacts/models/Contacts.php

/**
* Brief description of class.
*
* A longer description of the class.
*
* @package X2CRM.modules.contacts.models (path from x2engine/protected, slashes replaced with dots)
* @since 1.0 (version at which the class was first used)
*/
class Contacts
{
Documenting an attribute
Note the following: @var is followed immediately by the variable type of the attribute, then the description.
	/**
	 * @var string Description of attribute.
	 * @since 1.1.5 (version at which the attribute was first added/used)
	 */
	public $name;

Documenting a method
Note: the @param directive works in much the same way as “var”, whereas in @return, do not put a description, only the type of the variable that is returned by the method. If a parameter or return value does not always have the same type/class, use “mixed” for the type and explain in the description of the parameter or whole method (if the return value) when, why, and how the type or class of value should change. This will help avoid coding errors that arise from nonexistent attributes or undefined indices.
/**
	 * Brief description of method
	 *
	 * Optional, longer description of the method.
	 *
	 * @param integer $id Description of parameter. (Note: may span multiple lines if need be)
	 * @param mixed $pageSize Description of parameter.
	 * @return SmartDataProvider (note how it need not be built-in PHP type; it could be any class)
	 */
	public static function searchList($id,$pageSize=null)
	{
		...
	}
Linking to other classes and attributes
Use the syntax {@link [object]} to generate links. The type of link generation shown here (i.e. “this method is called by”)  isn’t really necessary; the documentation generator will show all the instances of where a method is called, and what other methods it calls or classes it uses. Links will thus be more useful for distinguishing between references at other locations, or for referencing another object when describing the current one in terms of it, or anything else a link could be used for.
/**
	 * Brief description of method.
	 *
Link to a method or attribute within the same class: it is not necessary to prefix with the class name, nor to include parentheses at the end of the property name
Link to a method or attribute within another class: Prefix with the class name followed immediately by a double-colon. 
Link to another class: Use just the class name.
 * This method is called by {@link searchAccount}. It is similar to 
 * the {@link Actions::searchBase} method in {@link Actions}
	 *
	 * @param integer $id Brief descriptionLonger description of parameter
	 * @param integer $pageSize Brief description
	 * Longer description
	 * @return SmartDataProvider (note how it need not be built-in PHP type; it could be any class)
	 */
	public static function searchBase($criteria)
	{
		...
	}
}