19

jsdoc如何指示@param是MouseEvent？HTMLElement DIV？

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

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

2 回答 2

17

实际上，您最好使用@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
 */

如果要引用另一个 doclet 中的事件，则需要注意 JSDoc 会自动将字符串event:添加到每个事件名称之前，以充当一种仅用于事件的命名空间。这意味着当从其他 doclet 引用事件时，您需要包含该“命名空间”，除了 and 的情况@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');
}
于 2014-03-14T00:12:41.500 回答
14 
/**
 * @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

于 2013-08-13T18:55:27.527 回答