javascript - 使用@method 或@property 的JSDoc 对象方法？

Question

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() {}

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

Answer 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 这是一个类，然后将它不是的放入文档中，但我发现这是让 jsdoc 做我想做的事情的最不令人反感的方式。我希望随着 jsdoc 的发展，这种解决方法最终会过时。