如何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编写此代码,只是为了使代码更简单一些.

通常,您需要将事件类型附加到某个名称空间,类,名称等.因为您尝试记录本机事件类型,所以使用"document"可能有意义(或窗口,或全局,或本机,或其他你喜欢)

/**
 * @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:到每个事件名称中,以充当事件的一种命名空间.这意味着你需要包括"命名空间"从其他的doclet指事件时,除了在的情况下@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');
}

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