Wie zu jsdoc zeigen, dass @param das MouseEvent ist?

Question

Wie zu jsdoc zeigen, dass @param das MouseEvent ist? das HTMLElement DIV?

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

Eigentlich würde man mit dem @event Tag besser dran, um den richtigen Ereignistyp zu dokumentieren, wie es mit anderen ereignisbezogene Tags wie @fires integriert und @listens in einer Weise, dass @typedef nicht. Abhängig von der gewünschten Detailstufe können Sie sie sogar mit einem Namespace versehen. Hier sind die Grundlagen - ich schreibe dies wie Sie jQuery verwenden, nur um den Code ein wenig einfacher zu machen.

---

Im Allgemeinen werden Sie Ereignistypen zu einem gewissen Namespace, Klasse, Name usw. anhängen möchten Da Sie eine native Ereignistyp zu dokumentieren sind versucht, mit „Dokument“ könnte Sinn (oder Fenster machen, oder global, oder native, oder was auch immer Sie mögen)

/** 
* @namespace document 
*/ 

Wenn Sie wollten, Sie noch detailliertere bekommen konnte und etwas tun, wie

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

Aber für die Zwecke dieser Diskussion werden wir nur bleib bei document.

Mausereignisse haben viele Eigenschaften, aber Sie müssen nur diejenigen dokumentieren, die Ihnen wichtig sind. Hier ist eine generische typedef genannt, die einige der Eigenschaften am häufigsten verwendet wird, definiert, wenn sie mit jQuery Ereignissen zu tun:

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

Jetzt haben wir dokumentiert, welche Art von Daten in einem Maus-Ereignisse sein sollte, so können wir verschiedenes Ereignis definieren Jetzt schreiben Sie und stellen Sie sicher, dass ihre Eigenschaften dokumentiert sind, ohne sich zu sehr zu wiederholen. Sie geben an, dass das Ereignis Teil des entsprechenden Namespaces ist, indem Sie zuerst den Namespace deklarieren, dann ein "#" und dann den Ereignisnamen.

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

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

Eine alternative Möglichkeit, diese Ereignisse und ihre Eigenschaften zu definieren, können Sie unter der Annahme, für jedes Ereignis über die gleichen Eigenschaften sich nicht, wäre so etwas wie dies zu tun:

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

Wenn Sie möchten, Um auf ein Ereignis in einem anderen Doclet zu verweisen, müssen Sie beachten, dass JSDoc automatisch die Zeichenfolge event: jedem Ereignisnamen voranstellt, um als eine Art Namespace nur für Ereignisse zu fungieren. Dies bedeutet, dass Sie diesen "Namespace" einschließen müssen, wenn Sie auf das Ereignis von anderen Doclets verweisen, außer im Fall von @fires und @listens, da der Namespace event: impliziert ist.

// 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'); 
}