JSDoc: documenting event listeners properly

Question

Ive been learning how to use JSDoc with my projects, I mostly understand how to use it with the exception of 1 or two things. One of these things being documenting event listeners.

Ive seen the documentation on the @listens, but the explanation/example they give is not making sense to me. Here’s a link to the page: https://jsdoc.app/tags-listens.html

I was wondering if anyone has a better way of explaining it to me, or maybe an example of how to document a basic event listener. (I’ll provide one below.)

document.getElementById('some_element')
  .addEventListener('mousedown', function () {
    // some code
});

Thanks.

Answer 1

Extending on my comment above, I figure that the following would be an acceptable way to document that line of code, in which document is the namespace, followed by the event name mousedown:

/**
 * Listen to mousedown event
 *
 * @type {HTMLElement} - the target of the event
 * @listens document#mousedown - the namespace and name of the event
 */

document.getElementById('some_element').addEventListener('mousedown', function () {
  // Some code
});