grunt-appular-docs

Generate documentation for Appular projects with source comments

grunt-appular-docs

Generate documentation for Appular projects with source comments

This plugin requires Grunt ~0.4.1

If you haven't used Grunt before, be sure to check out the Getting Started guide, as it explains how to create a Gruntfile as well as install and use Grunt plugins. Once you're familiar with that process, you may install this plugin with this command:

npm install grunt-appular-docs --save-dev

Once the plugin has been installed, it may be enabled inside your Gruntfile with this line of JavaScript:

grunt.loadNpmTasks('grunt-appular-docs');

In your project's Gruntfile, add a section named docs to the data object passed into grunt.initConfig().

grunt.initConfig({
  docs: {
    build: {
      options: {
        // Task-specific options go here. 
      },
      files: {
        // Target-specific file lists and/or options go here. 
      }
    }
  }
})

Type: Boolean Default value: false

If true generated JSON will be pretty.

grunt.initConfig({
  docs: {
    build: {
      options: {},
      files: {
        'dest/default_options': ['src/path/to/appular/folder/**/*.js'],
      }
    }
  }
})
grunt.initConfig({
  docs: {
    build: {
      options: {
        pretty: true
      },
      files: {
        'dest/default_options': ['src/path/to/appular/folder/**/*.js'],
      }
    }
  }
})

Documentation for this task to extract can be added by using inline commenting using the tags documented below.

/*
 * @appular name [version][ - description]
 */

The @appular block needs to appear at the top of any module that you want to document. Avaliable tags to use in this block include:

  • @define path/used/in/requirejs
  • @link http://url.documentation.com

Example - Defining and appular module named user bar

/*
 * @appular userBar v1.0.1 - designed to store variables for apps.
 * @define modules/user-bar/module
 * @link http://www.mysite.com
 */
/*
 * @function name[ - description]
 * @param name[:type][ - description]
 * @return name[:type][ - description]
 */

The @function tag can appear anywhere inside a module.

Example - Defining a function named render

/*
 * @function render - creates and inserts html for module
 * @param template:string - template for module
 * @param [data:object] - optional data for template
 * @return this:object - current view
 */
/*
 * @event name[ - description]
 */

The @event tag can appear anywhere inside a module.

Example - Defining a event named rendered

/*
 * @event rendered - fired when html is rendered
 */

Formatting requirements

  • name
    • required
    • camelcased
  • version
    • optional
    • needs to be in the format of v1.2.3 or v1.0
  • description
    • optional
    • needs to be preseeded by - for parser to recognize it.

In lieu of a formal styleguide, take care to maintain the existing coding style. Add unit tests for any new or changed functionality. Lint and test your code using Grunt.