Setting up a basic Gulpfile to run JSDoc

Question

I am struggling to understand what is missing from my current gulpfile in order to make JSDoc happy.

The code below does not cause any errors to be thrown, but looking at the index page of the documentation that is generated, it is clear my docs have not been formatted.

What am I missing here?

First, here is the function I want to document.

/**
 *   Returns the sum of a and b
 *   @param {Number} a
 *   @param {Number} b
 *   @return {Number} Sum of a and b 
 */
var sum = function(a, b){
  return a + b; 
};

Next, here is my gulpfile.js

var gulp = require('gulp');
var jsdoc = require('gulp-jsdoc');

gulp.task('js-doc', function(){
  return gulp.src([ 'app.js' ])
  .pipe(jsdoc.parser({}, 'test'))
  .pipe(jsdoc.generator('./docs'));
});

Once I run gulp js-doc, it creates the docs/ directory and builds out the documentation. However, visiting the index.html page in the browser reveals that no documentation was actually generated. When I look at app.js.html, another file generated by JSDoc, I see my code block but nothing on it has been parsed and turned into actual documentation. See screenshot below.

I think I'm missing some fundamental understanding of JSDoc or Gulp.

Answer 1

Figured it out:

npm install --save jsdoc gulp-shell

Then, inside your gulpfile.js paste in the following requires and task:

var gulp = require('gulp');
var shell = require('gulp-shell');

gulp.task('js-doc', shell.task(['./node_modules/jsdoc/jsdoc .']));

Now when you run gulp js-doc from the command line, you will generate the documentation.