Difference between revisions of "Writing Documentation"

Revision as of 01:34, 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 extends X2Model {

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

Syntax: @var [class] [description]

	/**
	 * @var string Description of attribute.
	 * @since 1.1.5 (version at which the attribute was first added/used)
	 */
	public $name;

        /**
	 * Brief description of method
	 *
	 * Optional, longer description of the method.
	 *
	 * @param integer $id Description of parameter.
	 * @param mixed $pageSize Description of parameter.
	 * @return SmartDataProvider
	 */
	public static function searchList($id,$pageSize=null)
	{
		...
	}

• <tt>@param syntax is: @param [class] [variable name] [description]
• The return type need not be built-in PHP type; it could be any class. Furthermore, the referenced class will be linked to.

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.
	 *
         * 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
	 */
	public static function searchBase($criteria)
	{
		...
	}
}

• 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.