1

放置处理事件的类（例如 ExtJS 子类）的方法的最佳 jsduck 标头是什么？Jsduck 似乎支持与 jsdoc 相同的标签，但我不确定@event 标签是否合适。

4

2 回答 2

3

JSDuck 和 jsdoc-toolkit 中的@event标签用于同一件事 - 记录由类触发的事件。

尽管 jsdoc-toolkit 文档在这部分看起来有点混乱，说 @event “描述了一个类处理的事件”，这可能使它看起来好像是为了记录侦听器。但是查看 jsdoc-toolkit问题日志，我们可以看到该功能的灵感来自于 YUI 中的事件，并且由于 ExtJS 也是从 YUI 发展而来的，它证实了@eventjsdoc-toolkit 和 JSDuck 中标签的语义平等。

但是，您似乎在询问事件处理程序 - 注册用于处理其他类触发的事件的方法。就像您有一个showPopup方法并且您想记录该方法处理click某个按钮上的事件一样。这与@event标签的含义相反。

但是你真的不应该以任何特殊的方式记录你的事件处理程序——只需将它们记录为普通方法就足够了。这与记录哪些其他方法调用特定方法相同 - 有时提供此信息可能很有用，但对所有方法都这样做只是愚蠢的。

In short. Methods and events are an interface to a class - they should get documented. Registering event handlers and calling methods is how you use the interface - that's an implementation detail, don't document it (at least not on the same level as your API documentation).

于 2013-02-11T03:20:55.130 回答
2

事件处理程序的文档记录应与任何其他方法（@method等）相同。@event是您将用于可侦听事件的标记：

function Foo() {
    /**
     * Fired when a sandwich is made
     * @event sandwich-made
     * @param {my.ns.Sandwich} sandwich
     */
    this.listen('sandwich-made', this.onSandwichMade, this);
}

您记录事件的位置是主观的。如果这是该事件的唯一入口点，或者如 JsDuck 文档中所示，当实际声明事件名称时，如果您确实使用方法正式添加它们，您可能会像我上面所做的那样做addEvents(events)。

文档不是明确的，但可能@event在给定对象的上下文中出现的任何标签都将与该对象相关联。

于 2012-04-03T16:44:59.223 回答