jsdoc - 如何用 jsdoc 描述 js 模块

Question

请向我解释描述此模块的最佳方式:

/**
 * Common util methods
 * @module Utils
 */
var Utils = (/** @lends module:Utils */
    function () {

    /**
     * Some default value
     * @constant
     * @public
     * @static
     * @type {string}
     */
    var staticConstantField = "Some value";

    //export to public access
    var exports = {
        staticConstantField: staticConstantField,
        getUrlArgs: getUrlArgs,
        isJSON: isJSON
    };

    return exports;

    /**
     * Return url arguments as associate array
     * @public
     * @static
     * @returns {Array} - url args
     */
    function getUrlArgs() {
        return [];
    }

    /**
     * Validate json
     * @public
     * @static
     * @param {string} json - json as string to validate
     * @returns {boolean}  - is json valid
     */
    function isJSON(json) {
        return true;
    }

    /**
     * Some private method
     * @private
     * @static
     * @param {string} json - json to parse
     * @returns {object}  - parsed object
     */
    function parseJson(json) {
        return {};
    }
})();

在这个例子中，我的@public 和@static 注释被忽略，所有@public 方法标记为“inner”，@private 方法标记为“private,inner”，return 语句被忽略。在生成的文档中，我看不到我可以使用哪些方法作为 api(我的代码中的“导出”对象)以及如果我返回

var exports = {
       anotherFieldName: staticConstantField,
       anotherGgetUrlArgsName: getUrlArgs,
       anotherIsJSONName: isJSON
};

此 API 不会出现在文档中。

生成的文档:

Answer 1

解决手头问题的快速方法是添加 @method methodName到每个功能。有了这个声明，@static属性在生成的 jsdoc 中被识别和引用。

/**
 * Common util methods
 * @module utils
 */
var utils = (/** @lends module:utils */ function () {
  /**
   * this variable is neither @static nor @public it's a @constant in a private scope, you can add a @private if you like
   * @constant
   * @private
   */
  var myConstant = 'foo';
  /**
   * @method myMethod
   * @static
   */
  function myMethod(){}

  return {
    myMethod: myMethod
  };
})();

尽管如此，我怀疑这个构造应该被视为一个模块而不是一个命名空间的对象文字。因此，我建议像这样声明它:

/**
 * Common util methods
 * @namespace
 */
var utils = (/** @lends utils */ function () {
  /**
   * @memberOf utils
   */
  function myMethod(){}

  return {
    myMethod: myMethod
  };
})();