© 2015 X2Engine Inc.

Difference between revisions of "Writing Documentation"

From X2Engine
Jump to: navigation, search
(Introduction)
 
(27 intermediate revisions by 2 users not shown)
Line 1: Line 1:
To write documentation to be included in the [http://doc.x2engine.com 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 [http://www.yiiframework.com/doc/api/ the Yii class reference]. The following general rules are noteworthy:
+
= Introduction =
 +
To write documentation to be included in the [http://doc.x2engine.com 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 [[wikipedia:Javadoc|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 [[yii:|The Yii class reference]]. The following general rules are noteworthy:
  
 
* Documentation comment blocks always begin with <code>/**</code> and begin every line (after indentation) with an asterisk, even if nothing else is on that line.
 
* Documentation comment blocks always begin with <code>/**</code> and begin every line (after indentation) with an asterisk, even if nothing else is on that line.
Line 10: Line 13:
 
<syntaxhighlight lang="php">
 
<syntaxhighlight lang="php">
 
/**
 
/**
* Brief description of class.
+
* Brief description of class.
*
+
*
* A longer description of the class.
+
* A longer description of the class.
*
+
*
* @package X2CRM.modules.contacts.models
+
* @package X2CRM.modules.contacts.models
* @since 1.0 (version at which the class was first used)
+
*/
*/
+
class Contacts extends X2Model {
class Contacts
 
{
 
// ...
 
 
</syntaxhighlight>
 
</syntaxhighlight>
 +
The <tt>@package</tt> 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 <tt>protected/</tt> (and <tt>framework/</tt> in Yii Framework).
  
Note the following:
+
= Documenting an attribute =
 
+
Syntax: <tt>@var [class] [description]</tt>
Documenting an attribute
+
<syntaxhighlight lang="php">
Note the following: @var is followed immediately by the variable type of the attribute, then the description.
 
 
/**
 
/**
 
* @var string Description of attribute.
 
* @var string Description of attribute.
* @since 1.1.5 (version at which the attribute was first added/used)
+
* @since 1.1.5
 
*/
 
*/
 
public $name;
 
public $name;
 +
</syntaxhighlight>
  
Documenting a method
+
= 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.
+
Syntax:  
/**
+
* Brief description, empty line, long description
* Brief description of method
+
* <tt>@param [class] [variable name] [description]</tt>
 +
* <tt>@return [class] [description of return value]</tt>
 +
 
 +
<syntaxhighlight lang="php">
 +
        /**
 +
* Generate a search from a contact list
 
*
 
*
* Optional, longer description of the method.
+
* Returns a DataProvider for all the contacts in the specified list,
 +
        * using this Contact model's attributes as a search filter.
 
*
 
*
* @param integer $id Description of parameter. (Note: may span multiple lines if need be)
+
* @param integer $id ID of the list to use for generating the search results.
* @param mixed $pageSize Description of parameter.
+
* @param mixed $pageSize Number of entries per page
* @return SmartDataProvider (note how it need not be built-in PHP type; it could be any class)
+
* @return SmartDataProvider The data provider used to generate the resulting grid view.
 
*/
 
*/
 
public static function searchList($id,$pageSize=null)
 
public static function searchList($id,$pageSize=null)
 
{
 
{
...
+
</syntaxhighlight>
}
+
 
Linking to other classes and attributes
+
Note:
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.
+
* 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 <tt>@return</tt>, 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 <tt>@param</tt> and <tt>@return</tt> (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. <tt>@return SmartDataProvider|Boolean</tt> .
 +
 
 +
= Linking to other classes and properties =
 +
Use the syntax <tt>{@link [object]}</tt> 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.
 +
<syntaxhighlight lang="php">
 +
        /**
 
* Brief description of method.
 
* 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
+
        * This method is called by {@link searchAccount}. It is similar to  
Link to a method or attribute within another class: Prefix with the class name followed immediately by a double-colon.
+
        * the {@link Actions::searchBase} method in {@link Actions}
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 $id Brief descriptionLonger description of parameter
* @param integer $pageSize Brief description
+
* @param integer $pageSize Description
* Longer description
+
* @return SmartDataProvider
* @return SmartDataProvider (note how it need not be built-in PHP type; it could be any class)
 
 
*/
 
*/
 
public static function searchBase($criteria)
 
public static function searchBase($criteria)
 
{
 
{
...
 
}
 
 
}
 
}
 
</syntaxhighlight>
 
</syntaxhighlight>
 +
* 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.
 +
 +
[[Category:Development]]

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.