Question

如何用jsdoc记录这样的模块？我尝试了很多版本，但无法让它发挥作用。 Funciton测试没有出现在文档中。

/**
 * Description of module, defines module for whole file
 *    
 * @module constructors
 * @exports app
 */


var app = (function() {
    /**
     * Description of function test
     */
    function test() {
        return '';
    }

    return {
        test: test
    }
}());

Answer 1

从版本3.2.2开始，jsdoc很容易被模块触发，解决方案是使用module:和模块名称来指定您要记录的实体所在的位置：

/**
 * Description of module, defines module for whole file
 *
 * @module constructors
 */

var app = (/** @lends module:constructors */ function() {
    /**
     * Description of function test
     */
    function test() {
        return '';
    }

    return {
        test: test
    }
}());

Answer 2

对我来说，使用JSDoc 3.4.0帮助了这个解决方案：

/**
 * @module array-cop
 */

/**
* @function
* @name Anonymous self-invoked function
* @description Call main module
* @param {Object} this Window for the browser
*/

(function(_) {

    var array_ = {
      /**
      * @function
      * @name check
      * @description Method for checking type of the source data.
      * @param {Array} arr  Source data.
      * @returns {Boolean} Returns true if Array.isArray, otherwise throw error.
      * @throws Will throw an error "Not an array" if the argument isn't array.
      */
        check: function(arr) {
            return Array.isArray(arr) || (function() {
                throw new Error("Not an array!");
            }());
        },

// Some code stuff

    /**
     * npm / <script> compatibility
     */

    if (typeof module !== "undefined" && module.exports) {
        module.exports = array_;
    } else {
        _.array_ = array_;
    }
}(this));

我还创建了生成JSDoc文档的gulp任务：

var gulp = require('gulp'),
    child_exec = require('child_process').exec;

// Task for generationg JSDoc
gulp.task('docs', function(done) {

    var settings = {
      docGenerator: "./node_modules/jsdoc/jsdoc.js",
      srcFile: "./src/array-cop.js",
      jsDocConfPath: "./jsdoc.json",
      docsOutputPath: "./docs"
    }

    child_exec('node '
                + settings.docGenerator
                + ' ' + settings.srcFile
                + ' -c ' + settings.jsDocConfPath
                + ' -d ' + settings.docsOutputPath, undefined, done);
});

运行gulp docs后

文档将被放置到./docs文件夹

jsdoc自我执行匿名函数

2 个答案: