什么是使用jsduck来记录事件处理程序的最佳方式?
什么是处理事件的类(例如ExtJS子类)的方法上的最佳类型的jsduck头? Jsduck似乎支持与jsdoc相同的标记,但我不确定@event标记是否合适。什么是使用jsduck来记录事件处理程序的最佳方式?
事件处理程序应与其他任何方法(@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
标签都将与该对象相关联。
不应该在事件下面使用@param标签来表示三明治,错误吗? – 2012-04-03 19:02:45
是的,这是更清洁。 – 2012-04-03 19:32:42
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文档不在同一级别)。
为什么不合适?你为什么不愿意效仿Ext的例子? – 2012-04-03 16:37:40