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

Question

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

Answer 1

事件处理程序应与其他任何方法（@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标签都将与该对象相关联。

Answer 2

JSDuck和jsdoc-toolkit中的@event标记意味着相同的事情 - 记录一个类被事件触发的事件。

虽然jsdoc-toolkit文档在这部分看起来有点混乱，说@event "describes an event handled by a class"，这可能使它看起来好像它是为了记录监听器。但是看看jsdoc-toolkit issue log我们可以看到这个特性受到YUI事件的启发，并且由于ExtJS也是从YUI开始发展的，它确认了@event标记在jsdoc-toolkit和JSDuck中的语义相同。

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

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

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