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

Ответ 1

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

Ответ 2

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

Обычно вам нужно присоединить типы событий к некоторому пространству имен, классу, имени и т.д. Поскольку вы пытаетесь документировать собственный тип события, использование "документа" может иметь смысл (или окно, или глобальное, или родное, или как вам угодно)

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

Если вы хотите ссылаться на событие в другом документе, вам нужно знать, что 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');
}