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

What is the best way to use jsduck to document event handlers?

本文关键字：最佳 方式 是什么 程序 jsduck 记录 事件处理 使用      更新时间：2023-09-26

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

JSDuck和jsdoc工具包中的@event标记用于相同的目的——记录类触发的事件。

尽管jsdoc工具箱文档在这方面看起来有点令人困惑，但说@event"描述了由类处理的事件"，这可能会让它看起来像是用来记录侦听器的。但查看jsdoc工具包的问题日志，我们可以看到该功能的灵感来自YUI中的事件，并且由于ExtJS也是从YUI发展而来的，它证实了jsdoc工具包和JSDuck中@event标记的语义相等。

然而，您似乎在询问事件处理程序，即为处理其他类引发的事件而注册的方法。就像您有一个showPopup方法，并且您希望记录该方法处理某个按钮上的click事件一样。这与@event标签的含义正好相反。

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

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

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

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标记都将与该对象相关联。

相关文章：