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 |
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.