How to write automatic documentation for gulp tasks?

Question

How can I use JSDoc to automatically generate documentation for the files that make up gulp tasks?

For example, I have a task file with a name assets. I would like to write some simple descriptions in the file itself, and JSDoc will automatically create the actual documentation using gulp.

var gulp          = require('gulp');
var documentation = require("jsdocs");

/**
 * A simple task to generate documentation for individual tasks.
 * @constructor
 */

gulp.task('docs',  function() {

  return gulp.src("./gulp/tasks/assets.js")
    .pipe(documentation())
    .pipe(gulp.dest('./md-documentation'));
});

I would like to automatically write documentation, simply describing the task on it.

How to do this using JSDoc?

Answer 1

I worked with jsdocs.

This assumes that I have a folder structure:

gulp/
    tasks/
    utils/
    index.js
    README.md
    config.js
src/
gulpfile.js
package.json
bower.json

The gulp task folder contains any gulp:

gulp docs.

gulp/tasks/_documentation.js

:

'use strict';

var gulp          = require('gulp'),
    runSequence   = require('run-sequence'),
    browserSync   = require('browser-sync'),
    jsdoc         = require('gulp-jsdoc');



/** @module Docs */

function Docs() {


    /**
     * A simple task to generate documentation for the gulp application. tasks.
     * @example gulp docs
     * @memberof module:Docs
     */

    var docs = {

        options: {
            srcFiles: ["./gulp/README.md", "./gulp/config.js", "./gulp/tasks/*.js"],
            destination: './doc/jsdoc/'
        },

        /**
         * A simple task to generate documentation for the gulp application. tasks.
         * @name docs
         * @example gulp docs
         * @memberoof module:Docs
         */     
        bundle: function() {
            gulp.task('docs',  function(cb) {
              return runSequence(
                'docs:build',
                'docs:serve',
                cb
              );
            });
        },
        build: function() {
            var options = this.options;

            var destination = options.destination;          


            var template = {                
                path : 'ink-docstrap',
                theme : 'flatly'
            };

            gulp.task('docs:build',  function() {
              gulp.src(options.srcFiles)
                .pipe(jsdoc.parser())
                .pipe(jsdoc.generator(destination, template))
            });
        },
        serve: function() {
            var options = this.options;
            gulp.task('docs:serve', function() {
              return browserSync.init({
                open: true,
                server: {
                  baseDir: options.destination,
                  // index : 'module-Config.html'
                },
                ghostMode: {
                  links: false
                }
              });

            });
        }
    };
    return docs;
}


module.exports = Docs();

jsDocs, , _documentation.js.

gulp docs, , - Modularized → .