Jak jsdoc wskazuje, że @param to MouseEvent?

Question

Jak jsdoc wskazuje, że @param to MouseEvent? 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

Właściwie to lepiej wyłączyć za pomocą znacznika @event udokumentowanie odpowiedniego typu zdarzenia, ponieważ integruje się z innymi znacznikami zdarzeń związanych i podobnych @fires@listens w sposób niezgodny z @typedef. W zależności od pożądanego poziomu szczegółowości można nawet nazwać je spacją. Oto podstawy - zamierzam napisać to tak, jak używasz jQuery, aby uczynić kod nieco prostszym.

---

Generalnie będziemy chcieli dołączyć typy zdarzeń do pewnego obszaru nazw, klasa, nazwa itp Skoro starasz się udokumentować natywną typ zdarzenia, używając „dokument” może mieć sens (lub okna, lub globalny, czy rodzimy, czy cokolwiek chcesz)

/** 
* @namespace document 
*/ 

Jeśli chcesz, możesz nawet dostać więcej ziarnistych i zrobić coś podobnego

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

Ale dla dobra tej dyskusji, będziemy po prostu trzymać się z document.

Wydarzenia z myszką mają wiele właściwości, ale naprawdę trzeba tylko udokumentować te, na których Ci zależy. Oto generic typedef nazywa który definiuje niektóre właściwości najczęściej stosowanych w kontaktach z wydarzeń jQuery:

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

Teraz mamy udokumentowane, jakie dane powinny być w przypadku myszy, dzięki czemu możemy określić inną imprezę typy teraz i upewnij się, że ich właściwości są dokumentowane bez powtarzania się za dużo. Wskazujesz, że wydarzenie jest częścią odpowiedniej przestrzeni nazw, deklarując najpierw przestrzeń nazw, następnie "#", a następnie nazwę zdarzenia.

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

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

Alternatywnym sposobem definiowania tych wydarzeń i ich właściwości, zakładając, że nie dbają o tych samych właściwościach każdym razie byłoby zrobić coś takiego:

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

Jeśli chcesz aby odwoływać się do zdarzenia w innym docletie, należy pamiętać, że JSDoc automatycznie wstawia ciąg event: do każdej nazwy zdarzenia, aby działał jako rodzaj przestrzeni nazw tylko dla zdarzeń. Oznacza to, że musisz uwzględnić tę "przestrzeń nazw" podczas odwoływania się do zdarzenia z innych docletów, z wyjątkiem przypadków @fires i @listens, ponieważ domniemana jest przestrzeń nazw 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'); 
}