feat(gen) add grunt-ngdoc

Add jsdoc to generated text and add grunt-ngdocs generated documentation
to /docs.

Add grunt-ngdocs to package.json & Gruntfile.js. Basic support in js & coffee
templates. Watch for changes in files & autoreload docs after regeneration.

Init work at yeoman#550

Author: marcin-wosinek

templates/coffeescript/app.coffee

@@ -1,5 +1,14 @@
 'use strict'
 
+=======
+###*
+ * @ngdoc overview
+ * @name <%= scriptAppName %>
+ * @description
+ * # <%= scriptAppName %>
+ *
+ * Main module of the application.
+###
 angular
   .module('<%= scriptAppName %>', [<%= angularModules %>])<% if (ngRoute) { %>
   .config ($routeProvider) ->

templates/coffeescript/controller.coffee

@@ -1,5 +1,12 @@
 'use strict'
 
+###*
+ * @ngdoc function
+ * @name <%= scriptAppName %>.controller:<%= classedName %>Ctrl
+ * @description
+ * # <%= classedName %>Ctrl
+ * Controller of the <%= scriptAppName %>
+###
 angular.module('<%= scriptAppName %>')
   .controller '<%= classedName %>Ctrl', ($scope) ->
     $scope.awesomeThings = [

templates/coffeescript/decorator.coffee

@@ -1,5 +1,12 @@
 'use strict'
 
+###*
+ * @ngdoc function
+ * @name <%= scriptAppName %>.decorator:<%= classedName %>
+ * @description
+ * # <%= classedName %>Ctrl
+ * Decorator of the <%= scriptAppName %>
+###
 angular.module("<%= scriptAppName %>").config ($provide) ->
   $provide.decorator "<%= cameledName %>", ($delegate) ->
     # decorate the $delegate

templates/coffeescript/directive.coffee

@@ -1,5 +1,12 @@
 'use strict'
 
+###*
+ * @ngdoc directive
+ * @name <%= scriptAppName %>.directive:<%= cameledName %>
+ * @description
+ * # <%= cameledName %>
+ * Directive to replace content with custom text.
+###
 angular.module('<%= scriptAppName %>')
   .directive('<%= cameledName %>', ->
     template: '<div></div>'

templates/coffeescript/filter.coffee

@@ -1,5 +1,13 @@
 'use strict'
 
+###*
+ * @ngdoc filter
+ * @name <%= scriptAppName %>.filter:<%= cameledName %>
+ * @function
+ * @description
+ * # <%= cameledName %>
+ * Filter to change your value.
+###
 angular.module('<%= scriptAppName %>')
   .filter '<%= cameledName %>', ->
     (input) ->

templates/coffeescript/service/constant.coffee

@@ -1,4 +1,11 @@
 'use strict'
 
+###*
+ * @ngdoc service
+ * @name <%= scriptAppName %>.<%= cameledName %>
+ * @description
+ * # <%= cameledName %>
+ * Constat in the <%= scriptAppName %>.
+###
 angular.module('<%= scriptAppName %>')
   .constant '<%= cameledName %>', 42

templates/coffeescript/service/factory.coffee

@@ -1,5 +1,12 @@
 'use strict'
 
+###*
+ * @ngdoc service
+ * @name <%= scriptAppName %>.<%= cameledName %>
+ * @description
+ * # <%= cameledName %>
+ * Factory in the <%= scriptAppName %>.
+###
 angular.module('<%= scriptAppName %>')
   .factory '<%= cameledName %>', ->
     # Service logic

templates/coffeescript/service/provider.coffee

@@ -1,5 +1,12 @@
 'use strict'
 
+###*
+ * @ngdoc service
+ * @name <%= scriptAppName %>.<%= cameledName %>
+ * @description
+ * # <%= cameledName %>
+ * Provider in the <%= scriptAppName %>.
+###
 angular.module('<%= scriptAppName %>')
   .provider '<%= cameledName %>', [->
 

templates/coffeescript/service/service.coffee

@@ -1,5 +1,12 @@
 'use strict'
 
+###*
+ * @ngdoc service
+ * @name <%= scriptAppName %>.<%= cameledName %>
+ * @description
+ * # <%= cameledName %>
+ * Service in the <%= scriptAppName %>.
+###
 angular.module('<%= scriptAppName %>')
   .service '<%= classedName %>', ->
     # AngularJS will instantiate a singleton by calling "new" on this function

templates/coffeescript/service/value.coffee

@@ -1,4 +1,11 @@
 'use strict'
 
+###*
+ * @ngdoc service
+ * @name <%= scriptAppName %>.<%= cameledName %>
+ * @description
+ * # <%= cameledName %>
+ * Value in the <%= scriptAppName %>.
+###
 angular.module('<%= scriptAppName %>')
   .value '<%= cameledName %>', 42

templates/common/root/_Gruntfile.js

@@ -38,10 +38,17 @@ module.exports = function (grunt) {
       coffeeTest: {
         files: ['test/spec/{,*/}*.{coffee,litcoffee,coffee.md}'],
         tasks: ['newer:coffee:test', 'karma']
+      },
+      js: {
+        files: ['.tmp/scripts/{,*/}*.js'],
+        tasks: ['ngdocs'],
+        options: {
+          livereload: true
+        }
       },<% } else { %>
       js: {
         files: ['<%%= yeoman.app %>/scripts/{,*/}*.js'],
-        tasks: ['newer:jshint:all'],
+        tasks: ['ngdocs', 'newer:jshint:all'],
         options: {
           livereload: '<%%= connect.options.livereload %>'
         }
@@ -392,6 +399,16 @@ module.exports = function (grunt) {
         cwd: '<%%= yeoman.app %>/styles',
         dest: '.tmp/styles/',
         src: '{,*/}*.css'
+      },
+      ngdocs: {
+        expand: true,
+        cwd: '<%%= yeoman.app %>/docs',
+        dest: '.tmp/docs/',
+        src: [
+          '*.{ico,png,txt}',
+          '.htaccess',
+          '*.html',
+        ]
       }
     },
 
@@ -422,6 +439,13 @@ module.exports = function (grunt) {
         configFile: 'karma.conf.js',
         singleRun: true
       }
+    },
+    ngdocs: {
+      options: {
+        dest: '.tmp/docs',
+        html5Mode: false
+      },
+      api: ['<% if (coffee) { %>.tmp<% } else { %><%%= yeoman.app %><% } %>/scripts/{,*/}*.js'],
     }
   });
 
@@ -436,6 +460,7 @@ module.exports = function (grunt) {
       'bowerInstall',
       'concurrent:server',
       'autoprefixer',
+      'ngdocs',
       'connect:livereload',
       'watch'
     ]);
@@ -462,6 +487,7 @@ module.exports = function (grunt) {
     'autoprefixer',
     'concat',
     'ngmin',
+    'ngdocs',
     'copy:dist',
     'cdnify',
     'cssmin',

templates/javascript/app.js

@@ -1,5 +1,13 @@
 'use strict';
 
+/**
+ * @ngdoc overview
+ * @name <%= scriptAppName %>
+ * @description
+ * # <%= scriptAppName %>
+ *
+ * Main module of the application.
+ */
 angular
   .module('<%= scriptAppName %>', [<%= angularModules %>])<% if (ngRoute) { %>
   .config(function ($routeProvider) {

templates/javascript/controller.js

@@ -1,5 +1,12 @@
 'use strict';
 
+/**
+ * @ngdoc function
+ * @name <%= scriptAppName %>.controller:<%= classedName %>Ctrl
+ * @description
+ * # <%= classedName %>Ctrl
+ * Controller of the <%= scriptAppName %>
+ */
 angular.module('<%= scriptAppName %>')
   .controller('<%= classedName %>Ctrl', function ($scope) {
     $scope.awesomeThings = [

templates/javascript/decorator.js

@@ -1,5 +1,12 @@
 'use strict';
 
+/**
+ * @ngdoc function
+ * @name <%= scriptAppName %>.decorator:<%= classedName %>
+ * @description
+ * # <%= classedName %>Ctrl
+ * Decorator of the <%= scriptAppName %>
+ */
 angular.module('<%= scriptAppName %>')
   .config(function ($provide) {
     $provide.decorator('<%= cameledName %>', function ($delegate) {

templates/javascript/directive.js

@@ -1,5 +1,12 @@
 'use strict';
 
+/**
+ * @ngdoc directive
+ * @name <%= scriptAppName %>.directive:<%= cameledName %>
+ * @description
+ * # <%= cameledName %>
+ * Directive to replace content with custom text.
+ */
 angular.module('<%= scriptAppName %>')
   .directive('<%= cameledName %>', function () {
     return {

templates/javascript/filter.js

@@ -1,5 +1,13 @@
 'use strict';
 
+/**
+ * @ngdoc filter
+ * @name <%= scriptAppName %>.filter:<%= cameledName %>
+ * @function
+ * @description
+ * # <%= cameledName %>
+ * Filter to change your value.
+ */
 angular.module('<%= scriptAppName %>')
   .filter('<%= cameledName %>', function () {
     return function (input) {

templates/javascript/service/constant.js

@@ -1,4 +1,11 @@
 'use strict';
 
+/**
+ * @ngdoc service
+ * @name <%= scriptAppName %>.<%= cameledName %>
+ * @description
+ * # <%= cameledName %>
+ * Constat in the <%= scriptAppName %>.
+ */
 angular.module('<%= scriptAppName %>')
   .constant('<%= cameledName %>', 42);

templates/javascript/service/factory.js

@@ -1,5 +1,12 @@
 'use strict';
 
+/**
+ * @ngdoc service
+ * @name <%= scriptAppName %>.<%= cameledName %>
+ * @description
+ * # <%= cameledName %>
+ * Factory in the <%= scriptAppName %>.
+ */
 angular.module('<%= scriptAppName %>')
   .factory('<%= cameledName %>', function () {
     // Service logic

templates/javascript/service/provider.js

@@ -1,5 +1,12 @@
 'use strict';
 
+/**
+ * @ngdoc service
+ * @name <%= scriptAppName %>.<%= cameledName %>
+ * @description
+ * # <%= cameledName %>
+ * Provider in the <%= scriptAppName %>.
+ */
 angular.module('<%= scriptAppName %>')
   .provider('<%= cameledName %>', function () {
 

templates/javascript/service/service.js

@@ -1,5 +1,12 @@
 'use strict';
 
+/**
+ * @ngdoc service
+ * @name <%= scriptAppName %>.<%= cameledName %>
+ * @description
+ * # <%= cameledName %>
+ * Service in the <%= scriptAppName %>.
+ */
 angular.module('<%= scriptAppName %>')
   .service('<%= classedName %>', function <%= classedName %>() {
     // AngularJS will instantiate a singleton by calling "new" on this function

templates/javascript/service/value.js

@@ -1,4 +1,11 @@
 'use strict';
 
+/**
+ * @ngdoc service
+ * @name <%= scriptAppName %>.<%= cameledName %>
+ * @description
+ * # <%= cameledName %>
+ * Value in the <%= scriptAppName %>.
+ */
 angular.module('<%= scriptAppName %>')
   .value('<%= cameledName %>', 42);