javascript – 如何编写gulp任务的自动文档？

2019年7月22日 108次阅读

如何使用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做到这一点？

最佳答案 我使用jsdocs工作了.

这假设您有一个文件夹结构：

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

gulp tasks文件夹包含任何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文档,它将产生一个新的浏览器实例,为你提供一个易于遵循模块化的干净网站 – >代码本身内包含所有文档的任务.

点赞