Javascript 带@method或@property的JSDoc对象方法?
JSDoc 3包括以下示例:Javascript 带@method或@property的JSDoc对象方法?,javascript,jsdoc,jsdoc3,Javascript,Jsdoc,Jsdoc3,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
/**
* 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
是不相关的。然而,这个方法听起来更正确,所以我想知道这是否是首选,或者我是否只是做了所有这些错误的事情(即,是否有一种更简单的方法来记录这种情况,而不创建类型)。@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的发展,这种解决方法最终会过时。另一种选择是使用@typedef为每个方法定义回调。然后,在所讨论对象的@typedef中,使用@property标记定义每个方法,并提供回调名称路径作为属性类型。这些将作为成员而不是方法显示在生成的文档中,但它们至少包括有关参数和返回值的信息。我目前正在使用这两种方法:
- 方法注释中的
,以及@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编译器的更改