0

我有一个使用闭包方法创建的 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它起作用（插入指向正确方法的链接），但我不想复制并粘贴该foo方法的文档以获得公共文档。

4

2 回答 2

3

我做了一些测试，我有好消息和坏消息:)。好消息是，您似乎可以通过将@borrows标签放在 Singleton doc 注释中来使其工作：

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

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

  • 该foo功能被标记static。这可能是一件好事，因为我理解您的代码似乎是准确的。
  • 使用当前显示的代码（即单例上没有更多方法等），您可以@lends完全省去标签，除非您为了清楚起见想要包含它。如果所有方法都列@borrows在顶级单例命名空间中，那么您不需要在返回的对象中进一步记录它们。同样，这可能是一件好事。
  • 坏消息是，除非明确标记了借用的方法，否则我无法使其工作@public- 这使得它在文档中冗余显示。我认为这是不可避免的——如果 jsdoc-toolkit 认为该方法是私有的，它不会创建文档，所以你不能参考它（我明白了WARNING: Can't borrow undocumented 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
  };
}());

...因为它复制了_footo的文档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）。

于 2011-04-13T20:55:15.727 回答
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 的文档。

于 2011-04-13T16:01:18.830 回答