JSDoc 正确记录事件监听器

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. Heres 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 show me an example of how you document a basic event listener. (Ill 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
});