Difference between revisions of "Writing Documentation"

Revision as of 00:53, 13 September 2012

To write documentation to be included in the Class Reference, it is merely required to write comments just before classes, attributes and methods that are formatted a certain way. Each of the following examples, and more, can be found in the Yii Framework source code, which uses much the same code documentation. The comments in Yii Framework are what are used to generate the Yii class reference. The following general rules are noteworthy:

• Documentation comment blocks always begin with /** and begin every line (after indentation) with an asterisk, even if nothing else is on that line.
• The first non-empty line in a comment block is the brief description.
• Following the brief description is an empty line, followed by the longer description.
• Most HTML tags in the comments will translate to HTML in the resulting documentation, i.e. lists (definition, ordered and unordered), anchor tags (although using the @link directive is far easier in most cases) and formatting such as em, strong and tt.

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
*/
class Contacts
{

The @package directive is used for categorization of classes, i.e. by namespace. Although it can be arbitrarily chosen, the convention used in most of Yii Framework's documentation and all of the class reference of X2Engine is that everything beyond the base package specifies the physical path to the file relative to protected/ (and framework/ in Yii Framework).

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