JSDoc 链接到回调函数

JSDoc links to callback function

本文关键字：函数 回调 链接 JSDoc      更新时间：2023-09-26

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

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

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

我遇到了同样的问题。如果您想要更好看的链接，您可以随时在描述中添加{@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并将其记录为模块的成员。

相关文章：