FIX refs GH-6 dgeni controller tag and add ngdoc tag to items

app/components/crud/crud_controller.js

@@ -7,7 +7,14 @@
  */
 
 'use strict';
-
+/**
+ * @ngdoc module
+ * @name ulakbus.crud
+ * @packageFile crud_controller.js
+ * @description
+ * ulakbus.crud module is the main module for ui. It interacts with backend and manipulate data to screen generically.
+ *
+ */
 angular.module('ulakbus.crud', ['ui.bootstrap', 'schemaForm', 'formService'])
     .config(function (sfErrorMessageProvider) {
         sfErrorMessageProvider.setDefaultMessage(302, 'Bu alan zorunludur.');
@@ -16,18 +23,24 @@ angular.module('ulakbus.crud', ['ui.bootstrap', 'schemaForm', 'formService'])
     })
 
     /**
+     * @ngdoc service
      * @name CrudUtility
+     * @module ulakbus.crud
      * @description
-     * Crud Utility is a service to provide functionality for Crud controllers
+     * Crud Utility is a service to provide generic functions for Crud controllers to format data and scope object.
      * @returns {object}
      */
     .service('CrudUtility', function ($log, $rootScope) {
         return {
             /**
+             * @ngdoc function
              * @name generateParam
+             * @module ulakbus.crud
              * @description
              * generateParam is a function to generate required params to post backend api.
              *
+             * scope
+             *
              * @param scope
              * @param routeParams
              * @param cmd
@@ -66,9 +79,11 @@ angular.module('ulakbus.crud', ['ui.bootstrap', 'schemaForm', 'formService'])
                 return scope;
             },
             /**
+             * @ngdoc function
              * @name listPageItems
+             * @module ulakbus.crud
              * @description
-             * listPageItems is a function to prepare objects to list in list page.
+             * listPageItems is a function to prepare objects to list in the list page.
              *
              * @param scope
              * @param pageData
@@ -104,7 +119,9 @@ angular.module('ulakbus.crud', ['ui.bootstrap', 'schemaForm', 'formService'])
     })
 
     /**
+     * @ngdoc controller
      * @name CRUDCtrl
+     * @module ulakbus.crud
      * @description
      * CRUDCtrl controller is base controller for crud module to redirect to related controller
      * This controller play an empty role for api calls.
@@ -119,7 +136,9 @@ angular.module('ulakbus.crud', ['ui.bootstrap', 'schemaForm', 'formService'])
     })
 
     /**
+     * @ngdoc controller
      * @name CRUDListFormCtrl
+     * @module ulakbus.crud
      * @description
      * CRUDListFormCtrl is the main controller for crud module
      * Based on the client_cmd parameter it generates its scope items.
@@ -127,6 +146,7 @@ angular.module('ulakbus.crud', ['ui.bootstrap', 'schemaForm', 'formService'])
      * There are 3 directives to manipulate controllers scope objects in crud.html
      *
      * The controller works in 2 ways, with and without pageData.
+     * pageData is generated by formService.Generator and it contains data to manipulate page.
      * If pageData has set, using Generator's getPageData() function, sets its scope items. After getting pageData
      * pageData must be set to `{pageData: false}` for clear scope of next job.
      *

app/zetalib/form_service.js

@@ -7,6 +7,7 @@
  */
 
 /**
+ * @ngdoc module
  * @name formService
  * @description
  *
@@ -19,14 +20,18 @@ angular.module('formService', ['ui.bootstrap'])
     })
 
     /**
+     * @ngdoc service
      * @name Generator
+     * @module formService
      * @description
      * form service's Generator factory service handles all generic form operations
      */
     .factory('Generator', function ($http, $q, $timeout, $sce, $location, $route, $compile, $log, RESTURL, $rootScope, Moment) {
         var generator = {};
         /**
+         * @ngdoc function
          * @name makeUrl
+         * @module formService
          * @description
          * this function generates url combining backend url and the related object properties for http requests
          * @param scope
@@ -37,11 +42,13 @@ angular.module('formService', ['ui.bootstrap'])
             return RESTURL.url + scope.url + getparams;
         };
         /**
+         * @ngdoc function
          * @name generate
+         * @module formService
          * @param scope
          * @param data
          * @description
-         * # generate function is inclusive for form generation
+         * - generate function is inclusive for form generation
          * defines given scope's client_cmd, model, schema, form, token, object_id objects
          *
          * @returns {string}
@@ -77,14 +84,16 @@ angular.module('formService', ['ui.bootstrap'])
             return scope;
         };
         /**
+         * @ngdoc function
          * @name group
+         * @module formService
          * @param scope
          * @description
          * group function to group form layout by form meta data for layout
          *
          * grouping will use an object like below when parsing its items:
          *
-         * grouping = [
+         * `grouping = [
          *  {
          *      "groups": [
          *          {
@@ -104,7 +113,7 @@ angular.module('formService', ['ui.bootstrap'])
          *      ],
          *      "layout": "2",
          *      "collapse": False
-         *  }]
+         *  }]`
          *
          * @returns {object}
          */
@@ -179,7 +188,9 @@ angular.module('formService', ['ui.bootstrap'])
             return scope;
         };
         /**
+         * @ngdoc function
          * @name prepareFormItems
+         * @module formService
          * @description
          * prepareFormItems looks up fields of schema objects and changes their types to proper type for schemaform
          * for listnode, node and model types it uses templates to generate modal
@@ -641,6 +652,10 @@ angular.module('formService', ['ui.bootstrap'])
             return generator.group(scope);
         };
         /**
+         * @ngdoc function
+         * @name dateformatter
+         * @module formService
+         * @description
          * dateformatter handles all date fields and returns humanized and jquery datepicker format dates
          * @param formObject
          * @returns {*}
@@ -655,10 +670,22 @@ angular.module('formService', ['ui.bootstrap'])
                 return newdatearray;
             }
         };
+        /**
+         * @ngdoc function
+         * @name doItemAction
+         * @module formService
+         * @description
+         * mode could be in ['normal', 'modal', 'new'] . the default mode is 'normal' and it loads data on same
+         * tab without modal. 'modal' will use modal to manipulate data and do all actions in that modal. 'new'
+         * will be open new page with response data
+         *
+         * @param $scope
+         * @param key
+         * @param todo
+         * @param mode
+         * @returns {*}
+         */
         generator.doItemAction = function ($scope, key, todo, mode) {
-            // mode could be in ['normal', 'modal', 'new'] . the default mode is 'normal' and it loads data on same
-            // tab without modal. 'modal' will use modal to manipulate data and do all actions in that modal. 'new'
-            // will be open new page with response data
             var _do = {
                 normal: function () {
                     $log.debug('normal mode starts');
@@ -691,6 +718,15 @@ angular.module('formService', ['ui.bootstrap'])
             return _do[mode]();
         };
 
+        /**
+         * @ngdoc function
+         * @name get_form
+         * @module formService
+         * @description
+         * Communicates with api with given scope object.
+         * @param scope
+         * @returns {*}
+         */
         generator.get_form = function (scope) {
             return $http
                 .post(generator.makeUrl(scope), scope.form_params)
@@ -699,6 +735,10 @@ angular.module('formService', ['ui.bootstrap'])
                 });
         };
         /**
+         * @ngdoc function
+         * @name get_list
+         * @module formService
+         * @description
          * gets list of related wf/model
          * @param scope
          * @returns {*}
@@ -711,6 +751,10 @@ angular.module('formService', ['ui.bootstrap'])
                 });
         };
         /**
+         * @ngdoc function
+         * @name get_wf
+         * @module formService
+         * @description
          * get_wf is the main function for client_cmd based api calls
          * based on response content it redirects to related path/controller with pathDecider function
          * @param scope
@@ -732,44 +776,50 @@ angular.module('formService', ['ui.bootstrap'])
                     }
                 });
         };
+        /**
+         * @ngdoc function
+         * @name isValidEmail
+         * @module formService
+         * @description
+         * checks if given value is a valid email address.
+         * @param email
+         * @returns {boolean}
+         */
         generator.isValidEmail = function (email) {
             var re = /^([\w-]+(?:\.[\w-]+)*)@((?:[\w-]+\.)*\w[\w-]{0,66})\.([a-z]{2,6}(?:\.[a-z]{2})?)$/i;
             return re.test(email);
         };
+        /**
+         * @ngdoc function
+         * @name isValidTCNo
+         * @module formService
+         * @description
+         * checks if given value is a valid identity number for Turkey.
+         * @param tcno
+         * @returns {boolean}
+         */
         generator.isValidTCNo = function (tcno) {
             var re = /^([1-9]{1}[0-9]{9}[0,2,4,6,8]{1})$/i;
             return re.test(tcno);
         };
+        /**
+         * @ngdoc function
+         * @name isValidDate
+         * @module formService
+         * @description
+         * checks if given value can be parsed as Date object
+         * @param dateValue
+         * @returns {boolean}
+         */
         generator.isValidDate = function (dateValue) {
             return !isNaN(Date.parse(dateValue));
         };
-        //generator.asyncValidators = {
-        //    emailNotValid: function (value) {
-        //        var deferred = $q.defer();
-        //        $timeout(function () {
-        //            if (generator.isValidEmail(value)) {
-        //                deferred.resolve();
-        //            } else {
-        //                deferred.reject();
-        //            }
-        //        }, 500);
-        //        return deferred.promise;
-        //    },
-        //    tcNoNotValid: function (value) {
-        //        var deferred = $q.defer();
-        //        $timeout(function () {
-        //            if (generator.isValidTCNo(value)) {
-        //                deferred.resolve();
-        //            } else {
-        //                deferred.reject();
-        //            }
-        //        }, 500);
-        //        return deferred.promise;
-        //    }
-        //};
-
 
         /**
+         * @ngdoc function
+         * @name pageData
+         * @module formService
+         * @description
          * pageData object is moving object from response to controller
          * with this object controller will not need to call the api for response object to work on to
          * @type {{}}
@@ -784,6 +834,10 @@ angular.module('formService', ['ui.bootstrap'])
 
 
         /**
+         * @ngdoc function
+         * @name pathDecider
+         * @module formService
+         * @description
          * pathDecider is used to redirect related path by looking up the data in response
          * @param client_cmd
          * @param $scope
@@ -795,7 +849,9 @@ angular.module('formService', ['ui.bootstrap'])
                 return;
             }
             /**
+             * @ngdoc function
              * @name redirectTo
+             * @module formService
              * @description
              * redirectTo function redirects to related controller and path with given data
              * before redirect setPageData must be called and pageData need to be defined
@@ -840,6 +896,16 @@ angular.module('formService', ['ui.bootstrap'])
             dispatchClientCmd();
         };
 
+        /**
+         * @ngdoc function
+         * @name get_diff
+         * @module formService
+         * @description
+         *
+         * @param obj1
+         * @param obj2
+         * @returns {{object}} diff object of two given objects
+         */
         generator.get_diff = function (obj1, obj2) {
             var result = {};
             angular.forEach(obj1, function (value, key) {
@@ -855,7 +921,17 @@ angular.module('formService', ['ui.bootstrap'])
             });
             return result;
         };
-
+        /**
+         * @ngdoc function
+         * @name get_diff_array
+         * @module formService
+         * @description
+         * extracts items of second array from the first array
+         * @param array1
+         * @param array2
+         * @param way
+         * @returns {Array}
+         */
         generator.get_diff_array = function (array1, array2, way) {
             var result = [];
             angular.forEach(array1, function (value, key) {
@@ -871,8 +947,16 @@ angular.module('formService', ['ui.bootstrap'])
             });
             return result;
         };
-
-        // get item unicode name from titleMap using this method
+        /**
+         * @ngdoc function
+         * @name item_from_array
+         * @module formService
+         * @description
+         * get item unicode name from titleMap
+         * @param item
+         * @param array
+         * @returns {*}
+         */
         generator.item_from_array = function (item, array) {
             var result = item;
             angular.forEach(array, function (value, key) {
@@ -884,8 +968,15 @@ angular.module('formService', ['ui.bootstrap'])
         };
 
         /**
-         * submit function is general function for submiting forms
+         * @ngdoc function
+         * @name submit
+         * @module formService
+         * @description
+         * submit function is general function for submiting forms.
+         * redirectTo param is used for redirect if return value will be evaluated in a new page.
+         *
          * @param $scope
+         * @param redirectTo
          * @returns {*}
          */
         generator.submit = function ($scope, redirectTo) {
@@ -948,7 +1039,9 @@ angular.module('formService', ['ui.bootstrap'])
     })
 
     /**
+     * @ngdoc controller
      * @name ModalCtrl
+     * @module formservice
      * @description
      * controller for listnode, node and linkedmodel modal and save data of it
      * @param items

docs/docs_conf.js

@@ -6,14 +6,16 @@ var Package = require('dgeni').Package;
 // Create and export a new Dgeni package called dgeni-example. This package depends upon
 // the jsdoc and nunjucks packages defined in the dgeni-packages npm module.
 module.exports = new Package('docs_conf', [
+    require('dgeni-packages/base'),
     require('dgeni-packages/jsdoc'),
     require('dgeni-packages/nunjucks'),
+    require('dgeni-packages/ngdoc'),
     require('dgeni-packages/links')
 ])
 
 // Configure our dgeni-example package. We can ask the Dgeni dependency injector
 // to provide us with access to services and processors that we wish to configure
-    .config(function(log, readFilesProcessor, templateFinder, writeFilesProcessor) {
+    .config(function(log, readFilesProcessor, templateFinder, writeFilesProcessor, computeIdsProcessor, computePathsProcessor, getAliases) {
 
         // Set logging level
         log.level = 'info';
@@ -26,7 +28,7 @@ module.exports = new Package('docs_conf', [
         readFilesProcessor.sourceFiles = [
             {
                 // Process all js files in `app` and its subfolders ...
-                include: 'app/components/**/*.js',
+                include: ['app/components/**/*.js', 'app/zetalib/*.js', 'app/shared/**/*.js'],
                 // ... except for this one!
                 exclude: 'app/**/*_test.js',
                 // When calculating the relative path to these files use this as the base path.
@@ -35,13 +37,24 @@ module.exports = new Package('docs_conf', [
             }
         ];
 
-        // Add a folder to search for our own templates to use when rendering docs
-        templateFinder.templateFolders.unshift(path.resolve(__dirname, 'templates'));
+        // Specify where the writeFilesProcessor will write our generated doc files
+        writeFilesProcessor.outputFolder  = 'docs/html';
+
+        templateFinder.templateFolders.push(path.resolve(__dirname, 'templates'));
 
         // Specify how to match docs to templates.
         // In this case we just use the same static template for all docs
-        templateFinder.templatePatterns.unshift('docs-template.html');
-
-        // Specify where the writeFilesProcessor will write our generated doc files
-        writeFilesProcessor.outputFolder  = 'docs/html';
+        templateFinder.templatePatterns.push('common.template.html');
+
+        computeIdsProcessor.idTemplates.push({
+            docTypes: [ 'controller' ],
+            idTemplate: 'module:${module}.${docType}:${name}',
+            getAliases: getAliases
+        });
+
+        computePathsProcessor.pathTemplates.push({
+            docTypes: [ 'controller' ],
+            pathTemplate: '${area}/${module}/${docType}/${name}.html',
+            outputPathTemplate: '/partials/${area}/${module}/${docType}/${name}.html'
+        });
     });
\ No newline at end of file

docs/templates/controller.template.html

+{% extends "api/object.template.html" %}
+
+{% block related_components %}
+{% if doc.providerDoc -%}
+<li>
+    <a href="{$ doc.providerDoc.path $}">- {$ doc.providerDoc.name $}</a>
+</li>
+{%- endif %}
+{% endblock %}