什麼是使用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文檔不在同一級別）。