javascript - 如何为 gulp 任务编写 Auto 文档？

Question

我如何使用 JSDoc 为构成 gulp 任务的文件自动生成文档？

例如，我有一个名为assets 的任务文件。我想在文件本身中写一些简单的描述，并让 JSDoc 使用 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'));
});

我想通过简单地描述上面的任务来自动编写文档。

我如何使用 JSDoc 执行此操作？

Answer 1

我使用 jsdocs 完成了这项工作。

这假设你有一个我做的文件夹结构:

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

gulp 任务文件夹，包含任何 gulp:

构建一个名为 docs 的 gulp 任务。

在 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，它将生成一个新的浏览器实例，为您提供一个干净的网站，带有易于遵循的模块化 -> 任务以及代码本身内的所有文档。