使用jsduck记录事件处理程序的最佳方法是什么？

Question

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

Answer 1

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

虽然jsdoc-toolkit文档在这部分看起来有点令人困惑，但是说@event "describes an event handled by a class"，这可能会让它看起来像是用于记录监听器。但是看看jsdoc-toolkit issue log我们可以看到这个特性的灵感来自于YUI中的事件，并且由于ExtJS也是从YUI中发展出来的，它确认了jsdoc-toolkit中@event标签的语义相等性。和JSDuck。

然而，您似乎在询问事件处理程序 - 已注册处理其他类触发的事件的方法。就像你有一个showPopup方法一样，你想要记录这个方法在某个按钮上处理click事件。这与@event标记的含义相反。

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

简而言之。方法和事件是类的接口 - 它们应该被记录下来。注册事件处理程序和调用方法是您使用接口的方式 - 这是一个实现细节，不记录它（至少与API文档不在同一级别）。

Answer 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);
}

您在哪里记录您的活动是主观的。你可以像我上面那样做，如果这是该事件的唯一入口点，或者as is shown in the JsDuck docs，当事件名称实际被声明时，如果你使用addEvents(events)方法正式添加它们。

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