jsdoc - jsdoc如何指示@param是MouseEvent？

Question

jsdoc如何指示@param是MouseEvent？ HTMLElement DIV？

/**
 * @param {MouseEvent} e
 */
 window.clickToButton = function(e) 
 {  
     console.dir(e);
 }

/**
 * @param {HTMLElement} d
 */
 window.clickToDiv = function(d)
 {
     console.dir(d);
 }

Answer 1

实际上你最好使用@event标记以记录正确的事件类型，因为它与其他与事件相关的标签(如 @fires)集成在一起和 @listens以 @typedef 的方式才不是。根据您想要的详细程度，您甚至可以命名它们。以下是基础知识——我将像使用 jQuery 一样编写此代码，只是为了让代码更简单一些。

通常，您需要将事件类型附加到某些命名空间、类、名称等。由于您正在尝试记录 native 事件类型，因此使用“文档”可能是有意义的(或窗口，或全局，或 native ，或其他你喜欢)

/**
 * @namespace document
 */

如果你愿意，你甚至可以变得更细化并做类似的事情

/**
 * @namespace root.events.mouse
 */

但为了便于讨论，我们将坚持使用 document。 .

鼠标事件有很多属性，但你真的只需要记录你关心的那些。这是一个名为 mouseEventParams 的通用 typedef它定义了处理 jQuery 事件时最常用的一些属性:

/**
 * @typedef {{
 *  target: element,
 *  which: number,
 *  pageX: number,
 *  pageY: number,
 *  clientX: number
 *  clientY: number
 * }} mouseEventParams
 */

现在我们已经记录了鼠标事件中应该包含哪些类型的数据，因此我们现在可以定义不同的事件类型并确保记录它们的属性而不会重复太多。您可以通过首先声明命名空间，然后是“#”，然后是事件名称来表明该事件是适当命名空间的一部分。

/**
 * Mousedown Event
 * @event document#mousedown
 * @type {mouseEventParams}
 */

/**
 * Mouseup Event
 * @event document#mouseup
 * @type {mouseEventParams}
 */

假设您不关心每个事件的相同属性，定义这些事件及其属性的另一种方法是执行以下操作:

/**
 * Mousedown Event
 * @event document#mousedown
 * @type {object}
 * @property {element} target
 * @property {number} which
 */

/**
 * Mouseup Event
 * @event document#mouseup
 * @type {object}
 * @property {number} pageX
 * @property {number} pageY
 * @property {number} clientX
 * @property {number} clientY
 */

如果要引用另一个 doclet 中的事件，则需要注意 JSDoc 会自动将字符串 event: 放在前面。到每个事件名称上，作为事件的一种命名空间。这意味着在引用其他 doclet 中的事件时需要包含该“ namespace ”， @fires 的情况除外。和 @listens ，如 event:命名空间是隐含的。

// Notice the inclusion of 'event:' between '#' and 'mousedown' on `@param`
// But you don't need it on 'listens'
/**
 * Handles mousedown events
 * @param  {document#event:mousedown} event
 * @listens document#mousedown
 */
var someMouseHandler = function (event) {
    console.log("mousedown event: ", e);
}

// Again, you don't need to include 'event:' for the `@fires` tag
/**
 * Triggers a mouseUp event
 * @param {element} element
 * @fires document#mouseup
 */
var triggerMouseUp = function (element) {
    $(element).trigger('mouseup');
}