Writing Documentation - Revision history

Demitri: /* Introduction */

2012-10-17T20:33:16Z

‎Introduction

Demitri: /* Introduction */

2012-10-17T20:32:20Z

‎Introduction

Demitri: /* Introduction */

2012-09-15T16:55:15Z

‎Introduction

Demitri: /* Documenting a method */

2012-09-15T16:54:20Z

‎Documenting a method

Demitri: /* Documenting a method */

2012-09-15T16:52:48Z

‎Documenting a method

Demitri at 23:45, 14 September 2012

2012-09-14T23:45:43Z

Demitri at 00:51, 14 September 2012

2012-09-14T00:51:01Z

X2WikiAdmin at 19:52, 13 September 2012

2012-09-13T19:52:21Z

X2WikiAdmin: /* Documenting a method */

2012-09-13T01:52:18Z

‎Documenting a method

X2WikiAdmin: /* Documenting an attribute */

2012-09-13T01:51:27Z

‎Documenting an attribute

@@ Line 1: / Line 1: @@
 = 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 [[wiki:Javadoc|Javadoc]] syntax
+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:

@@ Line 1: / Line 1: @@
 = 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. 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:
+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 [[wiki:Javadoc|Javadoc]] syntax
 * 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 1: / Line 1: @@
 = Introduction =
-To write documentation to be included in the [[x2doc:|X2CRM 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 [[yii:|The Yii class reference]]. The following general rules are noteworthy:
+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. 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.

@@ Line 39: / Line 39: @@
 <syntaxhighlight lang="php">
          /**
-	 * Brief description of method
+	 * Generate a search from a contact list
+	 *
-	 * Optional, longer description of the method.
+	 * Returns a DataProvider for all the contacts in the specified list,
+	 *
 	 * @param integer $id ID of the list to use for generating the search results.

@@ Line 33: / Line 33: @@
 = Documenting a method =
 Syntax:
 * <tt>@param [class] [variable name] [description]</tt>
-* <tt>@return [class]</tt>
+* <tt>@return [class] [description of return value]</tt>
 <syntaxhighlight lang="php">
@@ Line 42: / Line 43: @@
 	 * Optional, longer description of the method.
+	 *
-	 * @param integer $id Description of parameter.
+	 * @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
+	 * @return SmartDataProvider The data provider used to generate the resulting grid view.
 	 */
 	public static function searchList($id,$pageSize=null)

@@ Line 1: / Line 1: @@
 To write documentation to be included in the [[x2doc:|X2CRM 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 [[yii:|The Yii class reference]]. The following general rules are noteworthy:
@@ Line 6: / Line 7: @@
 * 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 <tt>@link</tt> directive is far easier in most cases) and formatting such as <tt>em</tt>, <tt>strong</tt> and <tt>tt</tt>.
-== Documenting a class ==
+= Documenting a class =
 Using the file, for example: <tt>protected/modules/contacts/models/Contacts.php</tt>:
 <syntaxhighlight lang="php">
@@ Line 20: / Line 21: @@
 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).
-== Documenting an attribute ==
+= Documenting an attribute =
 Syntax: <tt>@var [class] [description]</tt>
 <syntaxhighlight lang="php">
@@ Line 30: / Line 31: @@
 </syntaxhighlight>
-== Documenting a method ==
+= Documenting a method =
 Syntax:
 * <tt>@param [class] [variable name] [description]</tt>
@@ Line 54: / Line 55: @@
 * 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 attributes ==
+= 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">

← Older revision		Revision as of 00:51, 14 September 2012
Line 1:		Line 1:
−	To write documentation to be included in the [~~http~~:~~//doc.x2engine.com X2EngineCRM~~ 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:	+	To write documentation to be included in the [[x2doc:\|X2CRM 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 [[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.

← Older revision		Revision as of 19:52, 13 September 2012
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:	+	To write documentation to be included in the [http://doc.x2engine.com X2EngineCRM 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:

	* 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 25: / Line 25: @@
 	/**
 	 * @var string Description of attribute.
-	 * @since 1.1.5 (version at which the attribute was first added/used)
+	 * @since 1.1.5
 	 */
 	public $name;