JSDoc 链接到回调函数答案

【问题标题】：JSDoc links to callback functionJSDoc 链接到回调函数
【发布时间】：2017-08-12 05:26:23
【问题描述】：

我决定使用 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
 */

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

抱歉，长时间积累，并提前感谢您在我的文档工作中提供的帮助 :)

【问题讨论】：

标签： javascript node.js jsdoc

【解决方案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 并将其记录为模块的成员。

【讨论】：