-
Notifications
You must be signed in to change notification settings - Fork 80
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.
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
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"
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 }
*/
...
}
If option/method/event needs to be ignored/skipped from being parsed @Ignored@ flag should be included into the description. The purpose of the flag is to hide public option/method/event from a derived widget. The flag could also be applied on complex options and their members, as well as choice options which could be used in case the derived widget doesn’t support every specific choice.
If option/method/event needs to be marked as deprecated into the API, @Deprecated@ flag should be included into the description. The examples combine both skipped and deprecated flag
/* type="string" @Ignored@ Sets gets options supported by the igValidator widget.
Note: Validation rules of igValidator, such as min and max value/length are applied separately triggering errors,
while similar options of the editor work to prevent wrong values from being entered.
*/
property1: "property1",
/* type="string" Sets gets options supported by the igValidator widget.
Note: Validation rules of igValidator, such as min and max value/length are applied separately triggering errors,
while similar options of the editor work to prevent wrong values from being entered.
*/
property2: "property2",
/* type="string" @Deprecated@ Sets gets options supported by the igValidator widget.
Note: Validation rules of igValidator, such as min and max value/length are applied separately triggering errors,
while similar options of the editor work to prevent wrong values from being entered.
*/
property3: "property3",
/* type="off|biState|triState" Gets the type of checkboxes rendered before the tree nodes. Can be set only at initialization.
off type="string" Checkboxes are turned off and not rendered for the tree.
biState type="string" @Deprecated@ Checkboxes are rendered and support two states (checked and unchecked). Checkboxes do not cascade down or up in this mode.
triState type="string" @Ignored@ Checkboxes are rendered and support three states (checked, partial and unchecked). Checkboxes cascade up and down in this mode.
*/
property4: "property4",
/* type="string|number|null" @Deprecated@ Gets sets how the height of the control can be set."
string The height width can be set in pixels (px) and percentage (%).
number The height width can be set as a number in pixels.
null type="object" will fit the tree inside its parent container, if no other widths are defined.
*/
property5: null,
/* type="stranen|nenujen" @Deprecated@ Gets sets how the height of the control can be set."
stranen The height width can be set in pixels (px) and percentage (%).
*/
property6: null
settings: {
/* @Deprecated@ Settings related to built-in paging functionality */
paging: {
/* type="bool" Paging is not enabled by default */
enabled: false,
/* type="remote|local" Type @Deprecated@ for the paging operation
local type="string" Data is paged client-side.
remote type="string" @Ignored@ A remote request is done and URL params encoded
*/
type: "remote",
}
}
events: {
/* cancel="false" fired before @Deprecated@ databinding is performed
Function takes arguments evt and ui.
Use ui.owner to get a reference to the tree performing databinding.
*/
dataBinding: "dataBinding",
/* fired after databinding @Ignored@ is finished
Function takes arguments evt and ui.
Use ui.owner to get a reference to the tree performing databinding.
Use ui.dataView to get a reference to the data the tree has been databound to.
*/
dataBound: "dataBound"
}
checkState: function (node) {
/* Returns true if the provided node has its @Ignored@ checkstate checked and false otherwise.
paramType="object" optional="false" Specifies the jQuery object of the node element.
returnType="string" The checkbox state of the node.
*/
},
checkStateDep: function (node) {
/* Returns true if the provided node has @Deprecated@ its checkstate checked and false otherwise.
paramType="object" optional="false" Specifies the jQuery object of the node element.
returnType="string" The checkbox state of the node.
*/
}
The API parser supports two types of links inside description of option/method/event.
- Directs link – if somewhere into the description there is a token (chunk) matching http(s):// - this will automatically be replaced with anchor tag containing href and title matching the value.
- Mark Down format links – if somewhere into the description there is a token (chunk) matching
[link title](href)– the parser will replace the matching groups with anchor tag – where the title will be extracted from the contents inside the [ ], and the href attribute will be extracted from the contents inside ( ).
The API Parser now supports option/event/method link reference inside description.
For example if the iggrid has option autoGenerateColumns with description which talks about columns and we need a link to columns option - the link format inside the description should be as it follows:
[columns](ui.iggrid#options:columns)
The API option reference is constructed as follows <full_widget_name>#options:<path_to_option>
API Parser supports code snippet extraction from comment. Code snippets can be extracted from options, methods and events. The pattern which is used for code snippets extraction is as it follows:
``` code snippet goes here ```
Everything between the ``` and ``` is extracted and replaced from the comment. Here are examples how to enter code snippets inside the comments
addNode: function (node, parent, nodeIndex) {
/* Adds a new array of nodes to the tree.
New nodes are Skipped to the root
or to a specified parent node.
```
$(".selector").igTree("addNode", {Text: "New Node"}, parentNode);
```
paramType="object" optional="false" Specifies the data used to create the new node.
paramType="object" optional="true" Specifies the jQuery object of the parent node the nodes are to be appended to.
paramType="number" optional="true" Specifies the index at which the node to be inserted.
*/
}
Note
When there are parameters listed into the comment the code snippet should be added before them in order to be parsed correctly.
/* type="string|number|null" Gets sets how the height of the control can be set.
```
$("#data").igEditor({
property1: 20
})
```
string The height width can be set in pixels (px) and percentage (%).
number The height width can be set as a number in pixels.
null type="object" Will fit the tree inside its parent container, if no other widths are defined.
*/
property1: null
Note
In case of enum property, the code snippet should be inserted before the definition of the members – like is shown in the example.
/* cancel="false" fired before databinding is performed
```
$(document).delegate(".selector", "igtexteditorblur", function (evt) {
//return browser event
evt.originalEvent;
});
//Initialize
$(".selector").igTextEditor({
blur: function (evt) {
}
});
```
Function takes arguments evt and ui.
Use ui.owner to get a reference to the tree performing databinding.
*/
dataBinding: "dataBinding"