如何在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);
 }

- Danilovonline

Answer 1

实际上，最好使用@event标记来记录正确的事件类型，因为它与其他事件相关的标记（如@fires和@listens）集成在一起，而@typedef则没有。根据您想要的详细程度，甚至可以为它们命名空间。以下是基础知识 - 我将像您使用jQuery一样编写代码，以使代码更简单。

---

通常，您会希望将事件类型附加到某个命名空间、类、名称等。由于您正在尝试记录本机事件类型，因此使用“document”可能是有意义的（或者使用window、global、native或其他您喜欢的内容）。

/**
 * @namespace document
 */

如果你愿意的话，甚至可以更加详细地做一些像这样的工作。

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

但为了讨论方便，我们将仅使用document。

鼠标事件有很多属性，但你只需要记录你关心的那些。这里有一个通用的typedef，叫做mouseEventParams，它定义了处理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:，作为一种专门用于事件的命名空间。这意味着您需要在从其他doclets引用事件时包含该“命名空间”，但在@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');
}

- Isochronous

---

太棒了，我已经寻找这个解释很久了。非常感谢！ - sidneys

Answer 2

/**
 * @typedef {object} MouseEvent
 * @typedef {object} HTMLElement
 */

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

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

http://usejsdoc.org/tags-type.html

http://usejsdoc.org/tags-typedef.html

- Danilovonline

---

答案中的链接已失效 - DNS_PROBE_FINISHED_NXDOMAIN。 - Pang

答案中的链接已失效 - DNS_PROBE_FINISHED_NXDOMAIN。 - undefined