How to jsdoc indicate that @param is the MouseEvent?

Question

How to jsdoc indicate that @param is the MouseEvent? the HTMLElement DIV?

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

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

Answer 1

Actually you'd be better off using the @event tag to document the proper event type, as it integrates with other event-related tags like @fires and @listens in a way that @typedef does not. Depending on the level of detail you want, you could even namespace them. Here are the basics - I'm going to write this like you're using jQuery, just to make the code a little more simple.

---

Generally you'll want to attach event types to some namespace, class, name, etc. Since you're trying to document a native event type, using "document" might make sense (or window, or global, or native, or whatever you like)

/**
 * @namespace document
 */

If you wanted, you could even get more granular and do something like

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

But for the sake of this discussion, we'll just stick with document.

Mouse events have a lot of properties, but you really only need to document the ones you care about. Here's a generic typedef called mouseEventParams that defines some of the properties most often used when dealing with jQuery events:

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

Now we've documented what kind of data should be in a mouse event, so we can define different event types now and make sure their properties are documented without repeating ourselves too much. You indicate that the event is part of the appropriate namespace by first declaring the namespace, then a '#', then the event name.

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

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

An alternative way to define these events and their properties, assuming you don't care about the same properties for each event, would be to do something like this:

/**
 * 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
 */

If you want to refer to an event in another doclet, you need to be aware that JSDoc automatically prepends the string event: onto every event name, to act as a kind of namespace just for events. This means that you need to include that "namespace" when referring to the event from other doclets, except in the case of @fires and @listens, as the event: namespace is implied.

// 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