Как JSDoc указать, что @param является MouseEvent?

Как jsdoc указать, что @param является MouseEvent? на объект HTMLElement див?

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

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

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

12

на самом деле вам лучше использовать @event тег для документирования правильного типа события, поскольку он интегрируется с другими тегами, связанными с событиями, такими как @fires и @listens так что @typedef нет. В зависимости от уровня детализации вы хотите, вы можете даже имен их. Вот основы - я собираюсь написать это так, как вы используете jQuery, просто чтобы сделать код немного более простым.

обычно вы хотите присоединить типы событий к некоторому пространству имен, классу, имя и т. д. Поскольку вы пытаетесь документировать собственный тип события, использование "документа" может иметь смысл (или 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}
 */

An альтернативный способ определить эти события и их свойства, предполагая, что вас не волнуют одни и те же свойства для каждого события, было бы сделать что-то вроде этого:

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

если вы хотите ссылаться на событие в другом доклете, вы должны знать, что JSDoc автоматически добавляет строку event: на каждое имя события, чтобы действовать как своего рода пространство имен только для событий. Это означает, что вам нужно включить это "пространство имен" при ссылке на событие из других доклетов, кроме в случае @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');
}
11