API Documentation Guidelines

API Documentation Guidelines

Ignite UI API documentation is generated by an API parser tool and thus the documentation needs to follow a set format. When contributing new publicly visible options, events or methods to Ignite UI, please follow these guidelines.

Options

Every option is documented above the option definition, as a code comment. The options type, default value, and value types that are accepted by this option need to be documented. Also a description for the option's usage need to be provided. The comment format is as follows:

/* type="<Type1|Type2|Value1>" <Description>.
         Type1 <Type1 Description>.
         Type2 <Type2 Description>.
         Value1 type="<Value1 Type>" <Value1 Description>.
*/
width: null

A more specific example is as follows:

/* type="string|number|null" Gets sets the width of the control container.
         string The widget width can be set in pixels (px) and percentage (%).
         number The widget width can be set as a number in pixels.
         null type="object" No width will be applied to the container and it will be rendered by  
                            default for the browser rendering engine.
*/
width: null

Events

Every event is documented above the event definition, as a code comment. The event arguments, and whether the event is cancelable or not need to be documented. Also a description for the event's usage needs to be provided. The comment format is as follows:

/* cancel="<true|false>" <Event Description>
	Function takes arguments evt and ui.
	Use ui.<arg1> <arg1 description>.
	Use ui.<arg2> <arg2 description>.
	Use ui.<arg3> <arg3 description>.
*/
selectionChanging: "selectionChanging"

A more specific example is as follows:

/* cancel="true" fired before a new node is selected.
	Function takes arguments evt and ui.
	Use ui.owner to get a reference to the tree.
	Use ui.selectedNodes to get a reference to currently selected nodes.
	Use ui.newNodes to get a reference to the new nodes getting selected.
*/
selectionChanging: "selectionChanging"

Methods

Every method is documented inside the method definition, as a code comment on the first line/s of the method. The method parameters, parameter types, whether parameters are mandatory, or optional, and return type is documented. Also a description for the method's usage needs to be provided. The comment format is as follows:

findNodesByText: function (text, parent) {
	/* <Method Description>.
		paramType="<Param1 Type>" optional="<true|false>" <Param1 Description>.
		paramType="<Param2 Type>" optional="<true|false>" <Param2 Description>.
		returnType="<Return Type>" <Return Description>.
	*/
	...
}

Specific example:

findNodesByText: function (text, parent) {
	/* Retrieves all node objects with the specified text (case sensitive).
		paramType="string" optional="false" The text to search by.
		paramType="object" optional="true" The jQuery selected node element. If not specified then search would start from the root of the tree.
		returnType="object" Object description: { path: "node_path", element: jQuery LI Element, data: data, binding: binding }
	*/
	...
}