使用 JSDoc 记录私有构造函数

Posted 2023-02-25

【中文标题】使用 JSDoc 记录私有构造函数

【英文标题】：Documenting a private constructor with 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 等）尝试的所有组合似乎都无法从构建的文档中抑制它。

【参考方案1】：

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

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

【参考方案2】：

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

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

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