JSDoc Integration for Grunt

2.4.1 · maintenance · verified Tue Apr 21

grunt-jsdoc is a Grunt plugin designed to integrate JSDoc 3 documentation generation directly into a Grunt build process. It acts as a wrapper around the JSDoc tool, allowing developers to define documentation sources and output destinations within their Gruntfile.js. The current stable version is 2.4.1. Releases are infrequent, typically occurring to update the underlying JSDoc dependency (e.g., for security patches) or address minor compatibility issues. Its key differentiator is its tight integration into the Grunt ecosystem, providing a task-runner-centric approach to documentation, as opposed to running JSDoc directly from the command line or using a different build tool.

Common errors

```
Warning: Task "jsdoc" not found. Use --force to continue.
```
cause The Grunt plugin `grunt-jsdoc` has not been loaded in the Gruntfile.

fix Add `grunt.loadNpmTasks('grunt-jsdoc');` to your Gruntfile.js.
```
Error: Cannot find module 'ink-docstrap/template'
```
cause The `ink-docstrap` package is specified as a JSDoc template but is not installed or incorrectly referenced.

fix Ensure `ink-docstrap` is installed (`npm install --save-dev ink-docstrap`) and the `template` and `configure` paths in your Gruntfile configuration correctly point to `node_modules/ink-docstrap/template`.
```
Fatal error: The 'destination' property is required in your jsdoc options. See the jsdoc documentation.
```
cause The `destination` option, which specifies where the documentation will be generated, is missing from the `jsdoc` task configuration.

fix Add `destination: 'path/to/doc'` within the `options` object of your `jsdoc` task configuration in Gruntfile.js.
```
Error: spawn ENOENT
```
cause The JSDoc executable cannot be found by `grunt-jsdoc`, often due to environment path issues or missing JSDoc installation.

fix Explicitly set the `jsdoc` option to the path of the JSDoc binary, typically `jsdoc: './node_modules/.bin/jsdoc'`, or ensure JSDoc is correctly installed as a dependency.

Warnings

breaking The direct dependency on `ink-docstrap` was removed in version 1.0.0. Users upgrading from 0.x.x to 1.x.x or newer must explicitly install `ink-docstrap` if they intend to use it as a JSDoc template.
Fix: Install `ink-docstrap` separately: `npm install --save-dev ink-docstrap`.
breaking In version 2.0.0, the `private` option for JSDoc now follows JSDoc's default behavior, which means it is `false` by default. This change might hide documentation for private members if not explicitly configured.
Fix: Review JSDoc configurations for `private` option usage and set it explicitly to `true` if private members should be documented.
gotcha Node.js version requirements have increased over time. As of v2.4.1, Node.js >= 8.12.0 is required. Older Node.js versions may not be compatible, leading to build failures.
Fix: Ensure your Node.js environment meets the minimum requirement specified in the package's `engines` field (currently `'>= 8.12.0'`).
gotcha The `jsdoc` option allows specifying the path to the JSDoc executable. While often not needed, in some environments or complex setups, the `grunt-jsdoc` plugin might struggle to locate the correct JSDoc binary. This can lead to JSDoc not running or running with an incorrect version.
Fix: Explicitly set the `jsdoc` option in your Gruntfile to the full path of the JSDoc executable, e.g., `jsdoc: './node_modules/.bin/jsdoc'`.
gotcha Security updates to underlying dependencies like JSDoc or `marked` (a transitive dependency) are crucial. `grunt-jsdoc` v2.4.0 updated to JSDoc 3.6.0 for a security fix, and v2.3.1/v2.2.1 addressed regex DoS and XSS vulnerabilities in `marked` respectively. Running older versions could expose projects to these issues.
Fix: Always keep `grunt-jsdoc` updated to the latest stable version to benefit from security patches in its dependencies.

Install

npm install grunt-jsdoc npm
yarn add grunt-jsdoc yarn
pnpm add grunt-jsdoc pnpm

Imports

loadNpmTasks
wrong:
```
import { jsdoc } from 'grunt-jsdoc';
```
correct:
```
grunt.loadNpmTasks('grunt-jsdoc');
```
Grunt plugins are loaded via `grunt.loadNpmTasks` in the Gruntfile, not standard ES module imports.
jsdoc task configuration
```
grunt.initConfig({ jsdoc: { dist: { src: ['src/*.js'], options: { destination: 'doc' } } } });
```
The 'jsdoc' property within `grunt.initConfig` defines the task's behavior and options.
Calling the task
wrong:
```
require('grunt-jsdoc').run();
```
correct:
```
grunt.registerTask('default', ['jsdoc']);
```
The task is executed via the Grunt CLI (`grunt jsdoc`) or as part of a registered Grunt task.

Quickstart

This quickstart demonstrates how to configure and run the `grunt-jsdoc` task, including how to use an external JSDoc template like `ink-docstrap`. It shows a complete `Gruntfile.js` and a basic JavaScript file with JSDoc comments for generation.

/* Gruntfile.js */
module.exports = function(grunt) {

  // Project configuration.
  grunt.initConfig({
    pkg: grunt.file.readJSON('package.json'),
    jsdoc : {
        dist : {
            src: ['src/**/*.js', 'README.md'],
            jsdoc: './node_modules/.bin/jsdoc',
            options: {
                destination: 'doc',
                template: 'node_modules/ink-docstrap/template',
                configure: 'node_modules/ink-docstrap/template/jsdoc.conf.json',
                encoding: 'utf8'
            }
        }
    }
  });

  // Load the plugin that provides the 'jsdoc' task.
  grunt.loadNpmTasks('grunt-jsdoc');

  // Default task(s).
  grunt.registerTask('default', ['jsdoc']);

};

/* src/example.js */
/**
 * @module MyModule
 * Represents a simple example class.
 */
class MyClass {
  /**
   * Creates an instance of MyClass.
   * @param {string} name - The name of the instance.
   */
  constructor(name) {
    /** @private */
    this._name = name;
  }

  /**
   * Greets the given person.
   * @param {string} person - The person to greet.
   * @returns {string} A greeting message.
   */
  greet(person) {
    return `Hello, ${person}! My name is ${this._name}.`;
  }
}

module.exports = MyClass;

view raw JSON →