Come jsdoc indica che @param è MouseEvent?

Question

Come jsdoc indica che @param è MouseEvent? il DIV HTMLElement?

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

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

Answer 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

Answer 2

In realtà si sarebbe meglio usare il tag @event per documentare il tipo di evento corretto, come si integra con altri tag evento-correlati come @fires e @listens in un modo che non corrisponde a @typedef. A seconda del livello di dettaglio che desideri, potresti persino assegnare uno spazio ai nomi. Ecco le basi: scriverò questo come se stessi usando jQuery, solo per rendere il codice un po 'più semplice.

---

Generalmente si desidera associare tipi di evento a qualche spazio dei nomi, classe, nome, ecc Dal momento che si sta cercando di documentare un tipo di evento nativo, l'utilizzo di "documento" potrebbe avere senso (o finestra, o globale, o nativo, o quello che vuoi)

/** 
* @namespace document 
*/ 

Se si volesse, si potrebbe anche ottenere più granulare e fare qualcosa di simile

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

Ma per il bene di questa discussione, ci limiteremo a bastone con document.

Gli eventi del mouse hanno molte proprietà, ma è necessario solo documentare quelli che ti interessano. Ecco un typedef generico chiamato che definisce alcune delle proprietà più usati quando si tratta di eventi jQuery:

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

Ora abbiamo documentato che tipo di dati dovrebbe essere in un evento del mouse, in modo che possiamo definire evento diverso digita ora e assicurati che le loro proprietà siano documentate senza ripeterci troppo. Indica che l'evento fa parte dello spazio dei nomi appropriato dichiarando prima lo spazio dei nomi, quindi un '#', quindi il nome dell'evento.

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

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

Un modo alternativo per definire questi eventi e le loro proprietà, supponendo che non si preoccupano le stesse proprietà per ogni evento, sarebbe quello di fare qualcosa del genere:

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

Se si desidera per fare riferimento a un evento in un altro doclet, è necessario essere consapevoli che JSDoc mette automaticamente in primo piano la stringa event: in ogni nome di evento, per fungere da tipo di spazio dei nomi solo per gli eventi. Ciò significa che è necessario includere tale "spazio dei nomi" quando si fa riferimento all'evento da altri doclet, tranne nel caso di @fires e @listens, poiché è implicito lo spazio dei nomi 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'); 
}