Latest revision as of 20:33, 17 October 2012

Introduction

To write documentation to be included in the X2CRM Class Reference, it is merely required to write comments just before classes, attributes and methods that are formatted a certain way that is very similar (if not identical) to Javadoc syntax

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
	 */
	public $name;

Documenting a method

Syntax:

• Brief description, empty line, long description
• @param [class] [variable name] [description]
• @return [class] [description of return value]

        /**
	 * Generate a search from a contact list
	 *
	 * Returns a DataProvider for all the contacts in the specified list,
         * using this Contact model's attributes as a search filter.
	 *
	 * @param integer $id ID of the list to use for generating the search results.
	 * @param mixed $pageSize Number of entries per page
	 * @return SmartDataProvider The data provider used to generate the resulting grid view.
	 */
	public static function searchList($id,$pageSize=null)
	{

Note:

• The return type need not be built-in PHP type; it could be any class. Furthermore, the referenced class will be linked to.
• 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.
• Alternately, in both @param and @return (and in general), if there are only a few possible classes of the return value, they may be placed in a pipe-separated list, i.e. @return SmartDataProvider|Boolean .

Linking to other classes and properties

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