-
Notifications
You must be signed in to change notification settings - Fork 83
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.
*/
selectionChanging: "selectionChanging"
A more specific example is as follows:
/* cancel="true" fired before a new node is selected.
Function takes arguments evt and ui.
eventArgument="ui.owner" Get to get a reference to the tree.
eventArgument="ui.selectedNodes" Get a reference to currently selected nodes.
eventArgument="ui.newNodes" Get a reference to the new nodes getting selected.
*/
selectionChanging: "selectionChanging"
The API parser supports detailed description for event arguments.
In order to extract the event argument from the description the parser needs eventArgument flag followed by the argument name enclosed in quotes.
In order to extract the event argument type from the description the parser needs argType flag followed by the event argument type name enclosed in quotes. The supported event argument types are listed in the table.
The description for the event argument is extracted after the name and type flags.
Here is an code example which shows the usage of the three parts of the detailed description explained above.
eventArgument="evt" argType="event" Jquery event
The parser supports child event argulments. The only criteria the parser is using is the period (.) into the event argument name - where the value before the period is considered as a parent event argument. All the features exmplained for the event arguments from the above are valid for the child arguments too.
eventArgument="ui.dataRow" argType="$" The argument description of **dataRow** child argument.
eventArgument="ui.currentPageIndex" argType="number" The argument description of **currentPageIndex** child argument.
eventArgument="ui.domEl" argType="dom" The argument description of **domEl** child argument.
The table below lists the event argumet types supported by the API parser. The table consists of three columns. The first column is the key used by the parser to extract the event argument type from the comment. The second column is the event argument type shown in the API when the document is generated. The third column is the url used as link for the event argument type when generating the anchor tag.
| Key | Name Value | URL |
|---|---|---|
| string | String | http://api.jquery.com/Types/#String |
| event | Event | http://api.jquery.com/Types/#Event |
| number | Number | http://api.jquery.com/Types/#Number |
| $ | jQuery | http://api.jquery.com/Types/#jQuery |
| bool | Bool | http://api.jquery.com/Types/#Boolean |
| date | Date | http://api.jquery.com/Types/#Date |
| dom | domElement | http://www.w3schools.com/jsref/dom_obj_all.asp |
| jquery | jQuery | http://api.jquery.com/Types/#jQuery |
| array | Array | http://api.jquery.com/Types/#Array |
| function | Function | http://api.jquery.com/Types/#Function |
| object | Object | http://api.jquery.com/Types/#Object |
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"
Api Parser supports component name replacement. This feature is useful when you have derived widget and you don’t have to update the code snippet except the widget name – now you only need to use %%WidgetName%%, or %%WidgetNameLowered%% inside your code snippet and the API parser will automatically replace the pattern with the corresponding value.
Let’s say we have igBaseEditor and igTextEditor which derives from the first one and we have the following code snippet into the base widget:
```
$(document).delegate(".selector", "%%WidgetNameLowered%%blur", function (evt) {
//return browser event
evt.originalEvent;
});
//Initialize
$(".selector").%%WidgetName%%({
blur: function (evt) {
...
}
});
```
The parsed CDATA into the xml will be the following
igBaseEditor:
```
<codeSamples><![CDATA[
$(document).delegate(".selector", "igbaseeditorblur", function (evt) {
//return browser event
evt.originalEvent;
});
//Initialize
$(".selector").igBaseEditor({
blur: function (evt) {
...
}
});
]]></codeSamples>
```
igTextEditor:
```
<codeSamples><![CDATA[
$(document).delegate(".selector", "igtexteditorblur", function (evt) {
//return browser event
evt.originalEvent;
});
//Initialize
$(".selector").igTextEditor({
blur: function (evt) {
...
}
});
]]></codeSamples>
```
In non-visual components like dataSource the component name is a little bit different. For example in case the component which has been parsed is DataSource the pattern will be replaced with the following value: ig.DataSource
If we have igDatasource and igXMLDatasource which derives from the first and we have the following snippet into the base class:
```
$.%%WidgetName%%({
data: [
{
id: 1,
name: John
},
{
id: 2,
name: Michael
}
]
});
```
The parsed CDATA into the xml will be the following:
DataSource
```
<codeSamples><![CDATA[
$.ig.DataSource({
data: [
{
id: 1,
name: John
},
{
id: 2,
name: Michael
}
]
});
]]></codeSamples>
```
XMLDataSource
```
<codeSamples><![CDATA[
$.ig.XmlDataSource({
data: [
{
id: 1,
name: John
},
{
id: 2,
name: Michael
}
]
});
]]></codeSamples>
```
API parser supports defining parent widget name for every widget – then the parent widget name can be used for replacement into code snippets. The name should be defined using the parentWidgetName= flag followed by the widget name enclosed between double quotes (“). Here is an example:
$.widget("ui.igTreeGridPaging", $.ui.igGridPaging, {
/* parentWidgetName="igTreeGrid"*/
css: {
//Widget definition goes here
If we have the above definition and the following code snippet:
```
//Bind after initialization
$(document).delegate(".selector", "%%WidgetNameLowered%%contextrowrendering", function (evt, ui) {
//return the triggered event
evt;
// Get a reference to the %%WidgetName%% widget that fired the event
ui.owner;
// Get a reference to the first data row
ui.dataRow;
// Get current page index
ui.currentPageIndex;
// Get the current context row mode.
ui.owner.contextRowMode;
});
//Initialize
$(".selector").%%ParentWidgetName%%({
features: [{
name: "Paging",
contextRowRendering: function (evt, ui) { ... }
}]
});
```
The result after the parsing will be as it follows:
//Bind after initialization
$(document).delegate(".selector", "igtreegridpagingcontextrowrendering", function (evt, ui) {
//return the triggered event
evt;
// Get a reference to the igTreeGridPaging widget that fired the event
ui.owner;
// Get a reference to the first data row
ui.dataRow;
// Get current page index
ui.currentPageIndex;
// Get the current context row mode.
ui.owner.contextRowMode;
});
//Initialize
$(".selector").igTreeGrid({
features: [{
name: "Paging",
contextRowRendering: function (evt, ui) { ... }
}]
});