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

Question

JSDoc 3的文档包括以下示例:

/**
 * 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是不相关的.然而,方法听起来更正确,所以我想知道这是否是首选,或者我是否只是做了所有这些错误(即,如果有一种更简单的方法来记录这种情况,而不是创建一个类型).

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的发展而变得过时.

Answer 2

我目前正在使用两者：

• @tryAnyTag在方法注释中，以及
• @property在课堂评论中
  • 由于只有方法注释具有名称路径（@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 编译器的重大更改。