ng-mural-jsdoc

JSDoc 3 Template for AngularJS; customized for the Mural app. A JSDoc plugin and template for AngularJS, nothing else.

Features

• Common Template TOC, table of contents, for navigation by Directives, Services, Controllers, etc
• Read and process @ngdoc tag

Read More about JS-Doc and Ng-Doc

• Writing AngularJS Documentation - by Angular.
• Writing JsDoc Documentation

AngularJS specific ngdoc directives

In addition to the standard jsdoc directives, there are a number that are specific to the Angular code-base:

• @ngdoc - specifies the type of thing being documented. See below for more detail.
• @scope - specifies that the documented directive will create a new scope
• @priority - specifies the documented directive's priority
• @animations - specifies the animations that the documented directive supports
• @restrict - specifies how directives should be shown in the usage section. For example, for [E]lement, [A]ttribute, and [C]lass, use @restrict ECA
• @methodOf type - links a method to the object/service where it is defined
• @propertyOf type - links a property to the object/service where it is defined
• @eventOf type - links a method to the object/service where it is defined
• @eventType emit|broadcast - specifies whether the event is emitted or broadcast

The @ngdoc Directive

This directive helps to specify the template used to render the item being documented. For instance, a directive would have different properties to a filter and so would be documented differently. The commonly used types are:

• overview - Give an overview of the file/module being documented
• interface - Describe the interface of an object or service, specified by the @name directive. (abstract: use @object or @service instead)
• service - Describe an AngularJS service, such as $compile or $http, for instance.
• object - Describe a well defined object (often exposed as a service)
• function - Describe a function that will be available to other methods (such as a helper function within the ng module)
• method - Describe a method on an object/service
• property - Describe a property on an object/service
• event - Describe an AngularJS event that will propagate through the $scope tree.
• directive - Describe an AngularJS directive
• filter - Describe an AngularJS filter
• inputType - Describe a specific type of AngularJS input directive (such as text, email or checkbox)
• error - Describe a minErr error message

Usage Examples

/**
 * @ngdoc directive
 * @name NAME OF MODULE
 * @memberof NAME OF PARENT
 * @ctrl NAME OF CONTROLLER (if one)
 *
 * @classdesc
 *
 * @summary
 *   SUMMARY HERE
 *
 *   Restrict To:
 *     Element
 *
 * @example
 * Usage:
 *   NEED HTML EXAMPLE HERE
 *
 *
 * @requires {@Link LINKED NAME} 
 *
 * @param {LINK TO MOCKED OBJECT} PARAM NAME - PARAM DESCRIPTION.
 */

Install

$ npm install jsdoc ng-mural-jsdoc --save-dev

Run with grunt

1. add the following to the gulpfile.json

    module.exports = function (grunt) {
        'use strict';
       
        require('load-grunt-tasks')(grunt);
        grunt.loadNpmTasks('ng-mural-styleguide');
       
        //Initializing Grunt Configuration
        grunt.initConfig({
            //  Read in the Package File
            cfg: grunt.file.readJSON('config.json'),
            jsdoc: {
                dist: {
                    jsdoc: '/usr/local/bin/jsdoc',
                    src: [
                        'js/angular-apps/common/**/*.js',
                        '!js/angular-apps/_mural/_assets/bower_components/**',
                        './node_modules/ng-mural-jsdoc/Readme.md'
                    ],
                    options: {
                        destination: '<%= cfg.jsdoc.dest %>',
                        configure: './node_modules/ng-mural-jsdoc/conf.json',
                        template: './node_modules/ng-mural-jsdoc/template'
                    }
                }
            }
        });

2. run grunt task
   $ gulp jsdocs

Run with gulp

1. run gulp task

   `$ gulp Mural`

   NOTE: This assume you have the full Mural app installed already