javascript - JSDoc 链接到回调函数

Question

我决定使用 JSDoc 来记录我正在从事的项目。在阅读这里的使用指南和问题时，我仍然觉得我没有掌握 JSDoc 的一些核心概念，我在以下示例中说明了我的无能:http://jsfiddle.net/zsbtykpv/

/**
 * @module testModule
 */

/**
 * @constructor
 */
var Test = function() {
    /**
     * @callback myCallback
     * @param {Object} data An object that contains important data.
     */

    /**
     * A method that does something async
     * @param  {myCallback} cb a callback function
     * @return {boolean} always returns true
     */
    this.method = function(cb) {
        doSomethingAsync(function(data) {
            cb(data);
        });
        return true;
    }

}

module.exports = Test;

在这里，我定义了一个模块，指示了一个构造函数，并记录了一个将回调作为其参数之一的方法。听起来很简单，并且似乎遵循使用指南 http://usejsdoc.org/ 设置的指南.

但由于某种超出我理解的原因(这可能是我没有得到的核心概念)，它将回调 myCallback 显示为 testModule 而不是 Test 类的成员。难道它不应该默认为类的成员而不是模块的成员吗？这似乎也阻止了 JSDoc 建立指向回调定义的链接，这不是很有趣。

现在我意识到如果我写:

/**
 * @callback module:testModule~Test~myCallback
 * @param {Object} data An object that contains important data.
 */

/**
 * A method that does something async
 * @param  {module:testModule~Test~myCallback} cb a callback function
 * @return {boolean} always returns true
 */

我会得到我想要的行为。但这似乎是一种非常笨拙的做事方式，并且生成的链接远非漂亮。

很抱歉花了这么长时间，并提前感谢您对我的文档工作的帮助:)

Answer 1

我也遇到过同样的问题。如果您想要更好看的链接，您可以随时在描述中添加 {@link} 并在 @type 中使用规范名称，如下所示:

/**
 * @callback module:testModule~Test~myCallback
 * @param {Object} data An object that contains important data.
 */

/**
 * @param {myCallback} cb {@link module:testModule~Test~myCallback|myCallback}: a callback function
 * @return {boolean} always returns true
 */

我意识到输入起来有点令人沮丧，但它将 myCallback 记录为类而不是模块的成员，并且链接看起来不错。

如果您确实想要 @type 中的链接并且不关心它如何记录回调，您也可以这样做，这有点不那么冗长(以及我的内容)我决定为我的项目做):

/**
 * @callback myCallback
 * @param {Object} data An object that contains important data.
 */

/**
 * @param {module:testModule~myCallback} cb a callback function
 * @return {boolean} always returns true
 */

这将正确链接到 myCallback 并将其记录为模块的成员。