带有@method 或@property 的JSDoc 对象方法？答案

【问题标题】：JSDoc object methods with @method or @property?带有@method 或@property 的JSDoc 对象方法？
【发布时间】：2014-05-30 12:44:40
【问题描述】：

JSDoc 3 的documentation 包含此示例：

/**
 * The complete Triforce, or one or more components of the Triforce.
 * @typedef {Object} WishGranter~Triforce
 * @property {boolean} hasCourage - Indicates whether the Courage component is present.
 * @property {boolean} hasPower - Indicates whether the Power component is present.
 * @property {boolean} hasWisdom - Indicates whether the Wisdom component is present.
 */

/**
 * A class for granting wishes, powered by the Triforce.
 * @class
 * @param {...WishGranter~Triforce} triforce - One to three {@link WishGranter~Triforce} objects
 * containing all three components of the Triforce.
 */
function WishGranter() {}

我实际上是在创建一个类，该类接受一个实现接口MessageQueueConnector 的对象，该接口应该实现一个方法connectAndSubscribe。由于 Javascript 不区分成员函数和成员变量，所以使用属性是有意义的，而 JSDoc 的文档暗示 @method 是无关的。但是，方法听起来更正确，所以我想知道这是否是首选，或者我是否只是做错了所有这些（即，如果有一种更简单的方法首先记录这种情况，而无需创建类型）。

【问题讨论】：

标签： javascript jsdoc jsdoc3

【解决方案1】：

@typedef 的功能极其有限。您可以将方法定义为属性，但是您将无法以与真实类相同的方式记录参数。我为绕过这个限制所做的就是作弊。我使用@class，这样我就可以按照我想要的方式记录它并发出警告，它不是一个真正的类。所以：

/**
 * @classdesc Not a real class but an interface. Etc...
 *
 * @name MessageQueueConnector
 * @class
 */

/**
 * This method does...
 *
 * @method
 * @name MessageQueueConnector#connectAndSubscribe
 * @param {string} whatever Whatever this is.
 * @returns {Object} Description of return value.
 * @throws {SomeException} blah.
 */

请注意，上面的两个 doclet 不需要有任何关联的 JavaScript 代码。你不需要在 JavaScript 中创建一个假的类，你不需要创建一个假的方法等等。这就是为什么你需要使用@name。

我不喜欢告诉 jsdoc 这是一个类，然后在 doc 中输入它不是，但我发现这是让 jsdoc 做我想做的最不令人反感的方式。我希望随着 jsdoc 的发展，这种解决方法最终会过时。

【讨论】：

对我来说，当方法也通过@name InterfaceName#methodName 绑定到@interface 时，这也有效。
对我之前的评论的补充——它只在同一个项目中有效。但在导入包中不起作用。
每当我尝试声明我的班级 @implements {MessageQueueConnector} 时，我仍然会收到“找不到名称错误”

【解决方案2】：

我目前正在使用两者：

@tryAnyTag 在方法注释中，并且
@property在课堂评论中
- 由于只有方法 cmets 具有名称路径（类 cmets 中的 @property 标签没有），我们插入方法注释的名称路径作为 @property 的描述。

例子：

/** @module Example */

/**
 * @class module:Example.Car
 * @property {Function} start {@link module:Example.Car#start}
 * @property {Function} stop {@link module:Example.Car#stop}
 *
 */
class Car {

    /**
    * @method module:Example.Car#start
    *
    */
    function start () { /* function body */ }

    /**
    * @description You could use various other tags here, 
    * and JSDoc will still auto-assign the following namepath 
    * "module:Example.Car#stop" to this method
    *
    */
    function stop () { /* function body */ }
}

不幸的是，记录员不得不承担双重责任，因为 JSDoc 编译器不会自动解决这个问题。在某些时候，应该只有一种方法可以一次完成所有这些工作 - 但这意味着对 JSDoc 编译器的重大更改。

【讨论】：

【解决方案3】：

另一种选择是使用@typedef 为每个方法定义一个回调。然后，在相关对象的@typedef 中，使用@property 标记定义每个方法，并提供回调名称路径作为属性类型。这些将在生成的文档中显示为成员而不是方法，但它们至少会包含有关参数和返回值的信息。

【讨论】：