Frontend Documentation

Home » Support Library » Developer Support » Angular Guidelines » Frontend Documentation

Introduction

To automate documentation generation we use ngdoc extension of jsdoc. Review this document that contains available directives list: AngularJS Documentation

Doc-server builds documentation for directives and services only. That’s why these objects MUST be well doccumented. Controllers can be doccumented too, but this is mostly internal documentation for future support.

 

Doc Server installation

Use this repository for local documentation server https://github.com/sergeik/doc-server
Use next settings for config.js. Set proper folder paths in first.

 

module.exports = {
angularJS : [
‘c:/workspace/bactes360/bactes-user-interface/src/main/resources/META-INF/resources/resources/custom_modules/**/*.js’,
‘c:/workspace/bactes360/bactes-user-interface/src/main/resources/META-INF/resources/resources/modules/**/*.js’,
‘c:/workspace/ACM3/acm-user-interface/ark-web/src/main/webapp/resources/directives/**/*.js’,
‘c:/workspace/ACM3/acm-user-interface/ark-web/src/main/webapp/resources/filters/**/*.js’,
‘c:/workspace/ACM3/acm-user-interface/ark-web/src/main/webapp/resources/modules/**/*.js’,
‘c:/workspace/ACM3/acm-user-interface/ark-web/src/main/webapp/resources/services/**/*.js’
]
};

 

Source Code Documentation

Controllers

Controllers don’t provide methods, like services, that’s why functions should be documented with ‘function’ attribute:

/**
* @ngdoc function
* @name controllerFunc
*
* @description
* Controller’s function description
*
* @param {String} param Passed parameter
* @returns {Number} Result of function work
*/
function controllerFunc (param) {

}

 

Directives

/**
* @ngdoc directive
* @name global.directive:treeView
* @restrict E
*
* @description
*
* {@link https://github.com/Armedia/ACM3/blob/develop/acm-user-interface/ark-web/src/main/webapp/resources/directives/tree-view/tree-view.client.directive.js directives/tree-view/tree-view.client.directive.js}
*
* The treeView directive renders simple FansyTree based Tree View
*
* @param {expression} treeData Data structure used fot tree rendering
* @param {expression} onSelect Expression to evaluate upon tree item select.
*
* @example
<example>
<file name=”index.html”>
<tree-view treeData=”ordersData” onSelect=”selectOrder”>
</tree-view>
</file>
<file name=”app.js”>
angular.module(‘ngAppDemo’, []).controller(‘ngAppDemoController’, function($scope, $log) {
$scope.ordersData = [
{title: ‘Order 1’, key: ‘1’},
{title: ‘Order 2’, key: ‘2’, folder: true, children: [
{title: ‘Order 3’, key: ‘3’},
{title: ‘Order 4’, key: ‘4’}
]}
];$scope.selectOrder = function(selectedOrder){
$log.debug(selectedOrder)
};
});
</file>
</example>
*/
angular.module(‘directives’).directive(‘treeView’, [‘$q’,

 

Services

/**
* @ngdoc service
* @name upload-new-order.service:UploadNewOrder.NewOrderService
*
* @description
*
* {@link https://github.com/Armedia/bactes360/blob/develop/bactes-user-interface/src/main/resources/META-INF/resources/resources/modules/upload-new-order/services/new-order.client.service.js modules/upload-new-order/services/new-order.client.service.js}
*
* The NewOrderService used for single, spreadshett and batch documents upload.
*/
angular.module(‘upload-new-order’).factory(‘UploadNewOrder.NewOrderService’, [‘$http’,’$httpParamSerializer’, ‘Upload’,

 

Methods and functions

Methods

/**
* @ngdoc method
* @name sendBulkOrderFilesToAlfresco
* @methodOf upload-new-order.service:UploadNewOrder.NewOrderService
*
* @description
* Informs the server that it should upload the temp order files to the standard ArkCase
* pipeline process using the file types selected by the user in the ‘uploaded files’ menu
*
* @param {Array} files Array of uploaded files objects
* @returns {HttpPromise} Future info about uploaded files
*/
sendBulkOrderFilesToAlfresco: function (files) {

 

Functions

/**
* @ngdoc function
* @name sendBulkOrderFilesToAlfresco
*
* @description
* Informs the server that it should upload the temp order files to the standard ArkCase
* pipeline process using the file types selected by the user in the ‘uploaded files’ menu
*
* @param {Array} files Array of uploaded files objects
* @returns {HttpPromise} Future info about uploaded files
*/
sendBulkOrderFilesToAlfresco: function (files) {

 

Parameters with properties

http://usejsdoc.org/tags-param.html#parameters-with-properties

@param {Object} params Map of input parameter.
@param {Number} params.start zero based index of result starts from;
@param {Number} params.n max number of list to return;
@param {String} params.sort sort value. Allowed choice is based on backend specification;
@param {String} params.filters filter value. Allowed choice is based on backend specification

 

Code Snippet

* @example
* <pre>
* $scope.gridOptions.onRegisterApi = function ( gridApi ) {
* $scope.gridApi = gridApi;
* $scope.gridApi.selection.selectAllRows( $scope.gridApi.grid );
* };
* </pre>

 

Multi files example

@example
<example>
<file name=”index.html”>
<tree-view treeData=”ordersData” onSelect=”selectOrder”>
</tree-view>
</file>
<file name=”app.js”>
angular.module(‘ngAppDemo’, []).controller(‘ngAppDemoController’, function($scope, $log) {
$scope.ordersData = [
{title: ‘Order 1’, key: ‘1’},
{title: ‘Order 2’, key: ‘2’, folder: true, children: [
{title: ‘Order 3’, key: ‘3’},
{title: ‘Order 4’, key: ‘4’}
]}
];$scope.selectOrder = function(selectedOrder){
$log.debug(selectedOrder)
};
});
</file>
</example>

 

Common Ngdoc issues

Missing description

This is the comment at the top of the file.

Incorrect “methodOf” property.

Use the full name of the controller or service.

 

// incorrect
@methodOf Cases.StatusController// correct
@methodOf cases.controller:Cases.StatusController

 

Incorrect delimiters for parameter type declaration

Use {…}, not (…).

 

// incorrect
@param (String)

// correct
@param {String}

 

Failure to test your ngdoc annotations with the doc-server generator.

Install doc-server to test your documentation before commit. Instructions for doc-server installation are in this wiki.