【问题标题】:Documenting a private constructor with JSDoc使用 JSDoc 记录私有构造函数
【发布时间】:2015-02-10 07:39:51
【问题描述】:

我有一个类,其中可以静态调用各个方法,但会返回一个新的类实例以便链接,例如:

var builder = ns
  .setState('a', 'A')
  .setState('b', 'B');

Builder 的定义如下:

/** 
 * @module Builder 
 */

/**
 * @class Builder 
 */

/**
 * @private
 */
function Builder() {
  this.state = {
    query: {}
  };
}
Builder.prototype = {
  /**
   * @param {string} k - The key
   * @param {object} v - The value
   * @return {Builder}
   */
  setState: function(k, v) {
    var that = (this instanceof Builder) ? this : new Builder();
    that[k] = v;
    return that;
  }
  // Other properties and methods…
}

Builder 构造函数 从不 应该由用户代码显式调用,因此我不希望它出现在文档中。但是,我用 JSDoc 标签(例如@private@constructs 等)尝试的所有组合似乎都无法从构建的文档中抑制它。

【问题讨论】:

    标签: javascript constructor private jsdoc


    【解决方案1】:

    从 jsDoc 3.5.0 版本开始,您可以在类上使用标签@hideconstructor,告诉jsDoc 不要将构造函数包含在文档中。

    /**
     * @class Builder
     *
     * @hideconstructor
     */
    function Builder() {
        // implementation
    }
    

    【讨论】:

      【解决方案2】:

      您应该能够使用@ignore 指令来实现这一点。来自文档:

      @ignore 标记表示代码中的符号永远不应出现在文档中。此标记优先于所有其他标记。

      http://usejsdoc.org/tags-ignore.html

      【讨论】: