如何在 JSDoc 中记录事件处理程序？

Question

Suppose I have a class like this:

function myClass(q) {
  this.someFunction = function(e) {
      console.log("Click event");
  };

  jQuery(q).click(this.someFunction);
}

Is there a way to indicate to JSDoc that someFunction is not just a function that should be invoked directly but rather is an event handler ?

I see the @event tag but if I understand correctly this is more to document a function in my class that I consider to be an event (something the client code would register too and that my class will fire when needed) and not an event handler function ?

Answer 1

The keyword is @listens

Usage example:

/**
 * Outputs the event that happened
 *
 * @param {MyEvent} e - The observable event.
 * @listens MyEvent
 */
function myEventLogger(e) {
    console.log(e);
}

The corollary is the @fires keyword for raising the event.

Answer 2

No, there is no way to document an event handler.

So the best way is to document it as a normal function maybe writing in its description in bold text or upper case that is an "EVENT HANDLER".

You probably already now this, but just in case: you can write it in bold by simply wrapping the text into html tags <strong></strong> .

This answer is now deprecated but it does not let me delete it.