如何在 jsdoc-toolkit 中包含已经记录的方法？

Question

我有一个使用闭包方法创建的 JavaScript 单例对象：

/**
 * This is the singleton.
 *
 * @namespace window.Something.Singleton
 */
window.Something.Singleton = (function() {
  /**
   * Foo method.
   *
   * @return {String} this method always returns with <code>bar</code>
   */
  function _foo() { return "bar"; }

  /**
   * @lends window.Something.Singleton#
   */
  return {
    /**
     * @borrows window.Something-_foo
     * @function
     */
    foo: _foo
  };
}());

但是 jsdoc-toolkit 没有生成我想要的从 _foo 方法到 foo 方法的继承文档。

如果我写 @see 而不是 @borrows 它可以工作（插入正确方法的链接），但我不想复制和粘贴 < code>foo 方法也有公共文档。

Answer 1

我做了一些测试，有好消息和坏消息:)。好消息是，看起来您可以通过将 @borrows 标记放入 Singleton 文档注释中来使其工作：

/**
 * This is the singleton.
 *
 * @namespace Something.Singleton
 * @borrows Something.Singleton-_foo as foo
 */
Something.Singleton = (function() {
   // etc
})());

但这有几个后果，好的和坏的：

• foo 函数被标记为static。这可能是一件好事，因为根据我理解你的代码，它似乎是准确的。
• 使用当前显示的代码（即单例上不再有任何方法等），您可以完全放弃 @lends 标记，除非您为了清楚起见而想要包含它。如果所有方法都在顶级单例命名空间中列为 @borrows，那么您无需在返回的对象中进一步记录它们。再说一次，这可能是一件好事。
• 坏消息是，除非借用的方法被显式标记为 @public，否则我无法让它工作 - 这使得它在文档中冗余地显示。我认为这是不可避免的 - 如果 jsdoc-toolkit 认为该方法是私有的，它不会创建文档，因此您无法引用它（我得到警告：无法借用未记录的 Something.Singleton-_foo。 ）。如果该方法是公共的，它将显示在文档中。

所以这是有效的：

/**
 * This is the singleton.
 *
 * @namespace Something.Singleton
 * @borrows Something.Singleton-_foo as foo
 */
Something.Singleton = (function() {
  /**
   * @public
   * Foo method.
   *
   * @return {String} this method always returns with <code>bar</code>
   */
  function _foo() { return "bar"; }

  return {
    foo: _foo
  };
}());

...它将 _foo 的文档复制到 foo，但它也会在文档页面中显示 _foo ：

Method Summary
<inner>  _foo()
<static>  Something.Singleton.foo()

最好的解决方法可能就是完全忘记 @borrows 并在文档注释中明确将 _foo 命名为 Something.Singleton.foo ，将其标记为作为公共函数（如果您没有使用下划线命名内部函数，则可以省略 @public ，但这会告诉 jsdoc-toolkit 将其视为私有函数，除非另有说明）：

/**
 * This is the singleton.
 *
 * @namespace Something.Singleton
 */
Something.Singleton = (function() {
  /**
   * @name Something.Singleton#foo
   * @public
   * @function
   * Foo method.
   *
   * @return {String} this method always returns with <code>bar</code>
   */
  function _foo() { return "bar"; }

  return {
    foo: _foo
  };
}());

这将产生您正在查找的代码文档，并将注释放在与其相关的实际代码旁边。它并不能完全满足让计算机完成所有工作的需要 - 你必须在评论中非常明确 - 但我认为它与你最初的内容一样清晰，甚至更清晰，而且我不这么认为不要认为这需要更多的维护（即使在最初的示例中，如果您重命名了 Something.Singleton，您也必须更改所有文档注释）。

Answer 2

http://code.google.com/p/jsdoc-toolkit/wiki/TagBorrows

@borrows otherMemberName as thisMemberName
otherMemberName - 必需：其他成员的名称路径。
thisMemberName - 必需：该成员在此类中分配的新名称。

/** @constructor */
function Remote() {
}

/** Connect to a remote address. */
Remote.prototype.transfer = function(address, data) {
}

/**
 * @constructor
 * @borrows Remote#transfer as this.send
 */
function SpecialWriter() {
    this.send = Remote.prototype.transfer;
}

Remote#transfer 的任何文档也将显示为 SpecialWriter#send 的文档。