README.md

grunt-jsdoc

This plugin enables you to integrate the generation of comments based documentation into your Grunt build.

To your attention

The grunt team ask me to change the plugin name into NPM. The grunt-contrib namespace is now reserved to the tasks developed by the Grunt Team. I'll in a first time, deprecate the module in NPM and then update the name to grunt-jsdoc. You'll have to upgrade your package.json once the plugin will be removed from NPM.

Install

You need grunt >= 0.4 as well as node and npm installed and running on your system.

You also need java installed and available in your PATH.

Install this grunt plugin next to your project's Gruntfile.js with:

npm install grunt-jsdoc --save-dev

If you use the previous version of Grunt (0.3), you can install it with:

npm install grunt-jsdoc

Documentation

Configuration

Configure the plugin to your project's Gruntfile.js.

First, add the jsdoc entry to the options of the initConfig method :

grunt.initConfig({
    jsdoc : {
        dist : {
            src: ['src/*.js', 'test/*.js'], 
            options: {
                destination: 'doc'
            }
        }
    }
});

The supported options are

• src : (required) an array of pattern that matches the files to extract the documentation from. You can also add the pattern to a README.md file to include it in your doc as described there.
• dest : (alias to options.destination) set up the destination folder, the grunt way
• jsdoc: (optional) the path to the jsdoc bin (needed only for some border line cases)
• options : options used by jsdoc
  • destination: (required) the folder where the doc is generated
  • configure : (optional) path to a config file
  • template : (optional) path or name to a different template
  • private : (optional) include the private functions to the doc (true by default).
  • ... refer the usejsdocCli documentation for all the available options.

Then, load the plugin

grunt.loadNpmTasks('grunt-jsdoc');

Code Documentation

The current version supports only jsdoc3 documentation style. The sources configured must contains valid jsdoc3 tags. Consult the usejsdoc website for the details.

Templates

The plugin includes docstrap, as well as the default template provided by jsdoc3. You can have a look to the Gruntfile.js for the configuration.

Build

To generate the documentation, you need to call the jsdoc task :

$> grunt jsdoc

or integrate it to your build sequence :

grunt.registerTask('default', ['lint', 'test', 'jsdoc']);

Contributing

Any contribution is welcome! Please check the issues. Do some unit/integration tests as far as possible.

Release History

• 0.5.0 Move to NPM dependencies instead of git, jsdoc 3.2.2 (Fix #65)
  • 0.5.1 Update repo name to prevent confusion with previous version
• 0.4.0 Update to jsdoc 3.2.0 stable, Fix #37, add integration tests
  • 0.4.1 Fix #53 and #54
  • 0.4.2 Fix #57
  • 0.4.3 Grunt 0.4.2 compliance, upgrade to jsdoc 3.2.2 and undeprecate the dest option (#60, #63 and #66)
• 0.3.0 Partial rewrite, Fix #29 and minor typos fixs
  • 0.3.1 Fix #29
  • 0.3.2 Fix #32
  • 0.3.3 Fix #34 and #36
• 0.2.0 Migrate to grunt 0.4
  • 0.2.1 Fix #10
  • 0.2.2 Fix #11
  • 0.2.3 Fix #14 and #15
  • 0.2.4 Fix Jsdoc 3 dependency to 3.1.1 tag, enables jsdoc options #19, enable to add jsdoc path #13 and add peerDependencies
• 0.1.0 First release, includes basic support of jsdoc3
  • 0.1.1 Fix #2
  • 0.1.2 Fix #4
  • 0.1.3 Fix #7, Add feature #8
  • 0.1.4 Use child_process.spawn instead of exec to run the command

License

Copyright (c) 2012 Bertrand Chevrier
Licensed under the MIT license.