API Docs Syntax

Documentation Guidelines

To document the project we use ngdoc. ngdoc uses showdown which is a markdown implementation for most of the documentation.

Documentation syntax

You can find syntax instructions here:
showdown syntax guide (see combox on right hand corner for syntax guide).
Wrap your code samples in <pre></pre>

links

The syntax for links is as follows: the format is the link directive followed by the actual url and the name to display.

* External Link -  {@link http://angular-ui.github.com/ng-grid/ ngGrid}   
* Internal link - Internal: {@link pl.directive:plEntityGrid plEntityGrid}

you have two options to document with ngdoc:

Guides

create a guide by creating a document in the ui/docs/guide folder with the ngdoc extension The guide has to contain the following header followed by a blank line:
@ngdoc overview
@name
@description

you only have to change the guide name in the header. change anything else and you will not get documentation...

###Adding images to your guides Adding images uses standard img elements. Add the image to ui/docs/img/<your guide name>/ and reference it like so:
<img src="img/<guide name>/<image_name.ext>" alt="<alt text goes here>" />

code

ngdocs has several attributes that can be used in any context and are global. They are listed below:

    /**
    *@ngdoc  // the type of the documentation object being created. 
    *@name .: // the name attribute is created differently for different types
    *@param {||}   // you can have multiple param attributes per diretive
    *@param {type1=}  -  //adding a trailing equals sign to the the param attribute make the param optional
    *@description  //Any element can have a description element that start int he line after the description attribute.  It can be as long as need and supports showdown /html.
    *
    */

Directives

To document a directive you need to create the following header in your Javascript file:

/**
* @ngdoc directive // Mark the object as a directive
* @name pl.directive:entityPage //start with the module name. the second part is always directive. the directive name goes after the the column
* @restrict 'AC' //the elements the directive is restricted to.
* @element ANY //will create a usage example combined with restrict
* @priority 1000 //The higher the priority the sooner the directive gets compiled.
* @scope  //add this attribute if you create a scope in your directive.
**/

Services

Documenting services starts very similar to documenting a directive. We create the initial ngdoc directive

/**
 * @ngdoc service  //Mark the object as a service.
 * @name pl.myService // Provide the module and the service name
 * @requires $rootScope  // provide any dependencies. you can have multiple @requires lines
**/

Filters

Documenting filters is almost like documenting a function:

/**
 * @ngdoc filter
 * @name .filter: //  middle part is always filter 
 * @function // all filters are a function
 * 
 */
 

Object Parts

Methods

You can decorate your services' public methods

    /**
     * @ngdoc method
     * @name pl.service#method //.# 
     * @methodOf ng.service // .
     * @returns {string} What do I return // return type and description
     */

Properties

You can decorate your object properties

/**
 * @ngdoc property
 * @name .# //the name after the hash is important
 * @propertyOf . // the same part as above other than the hash
 * @returns {}  //required for a property.
 */

Properties can also use a simplified annotation. Properties can be defined as part of the of the main object decleration. Do not use.

    /**
    * @property {}  //Property description can be multiple line and supports showdown
    **/

events

/**
 * @ngdoc event
 * @name .# //the name after the hash is important
 * @eventOf . // the same part as above other than the hash
 * @eventType  on  // **`on`** is a keyword you can choose to either emit or broadcast on the target
 */