7

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是无关的。但是，方法听起来更正确，所以我想知道这是否是首选，或者我是否只是做错了所有这些（即，如果有一种更简单的方法首先记录这种情况，而无需创建类型）。

4

3 回答 3

13

@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 的发展，这种解决方法最终会过时。

于 2014-04-16T12:03:54.113 回答
3

我目前正在使用两者：

  • @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 编译器的重大更改。

于 2019-12-28T05:26:17.567 回答
1

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

于 2015-12-01T16:05:27.287 回答