如何在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工作（插入一个链接到正确的方法），但我不希望复制粘贴&文档为foo方法有一个公共的文档以及。

Answer 1

我做了一些测试，我有好消息和坏消息:)。好消息是，它看起来像你可以得到这个通过将@borrows标签在辛格尔顿文档注释工作：

/** 
* 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 ，将其标记为公共功能（你可以用@public免除，如果你没有名字带有下划线的内部函数，但是这告诉jsdoc的工具包把它当作私人除非特别指出）：

/** 
* 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; 
} 

远程＃传输的任何文档也将作为SpecialWriter＃send的文档出现。