Question

我有一个用single方法创建的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方法的文档也有公共文件。

Answer 1

我做了一些测试，我有好消息和坏消息:)。好消息是，看起来你可以通过将@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
  };
}());

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

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

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

@public

这将生成您正在寻找的代码文档，并将注释放在与其相关的实际代码旁边。它并不能完全满足计算机完成所有工作的需要 - 你必须在评论中非常明确 - 但我认为它与你原来的一样清晰，如果不是更清楚，我也不会我认为这需要更多维护（即使在原始示例中，如果重命名为/** * 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 }; }());，则必须更改所有文档注释。）

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。的文档。

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

2 个答案: