JSDoc 正确记录事件监听器

Question

我一直在学习如何在我的项目中使用JSDoc，大多数情况下我知道如何使用，但有一两个例外。其中之一是记录事件监听器。

我看过了@listens的文档，但他们给出的解释/示例对我来说不太清楚。这是页面链接：https://jsdoc.app/tags-listens.html 我想知道是否有人可以更好地向我解释它，或者可以向我展示如何记录一个基本的事件监听器（我将在下面提供一个示例）。

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

感谢

- Finchy Finchy

---

你所说的“文档化事件监听器”是什么意思？看起来你想问如何编写文档监听器。此外，提供一个链接到你不理解的具体文档可能会有帮助。最后，更多上下文代码对其他人也会有帮助，因为他们可以更容易地找出问题所在。你尝试过那个示例代码吗？如果尝试了，控制台会显示什么样的错误信息？ - nunop

@rocha感谢您的评论。我会编辑我的问题，使其更具体。只是回答您的一些问题，我的问题不在于代码，我正在使用一个名为JSDoc的文档工具，我想知道如何正确地记录侦听器。我将在我的问题中提供一个链接。 - Finchy Finchy

明白了，感谢解释。即使JSDoc中的@events和@listens标签的文档不太有用，这个特定的代码行似乎很容易记录，这是具有讽刺意味的。首先，可能需要引用HTML元素作为类型：@type {HTMLElement}。然后可能需要类似于以下内容：@event document#mousedown或@listens document#mousedown，其中您首先声明命名空间，然后是#，最后是事件名称。 - nunop

Answer 1

延伸我之前的评论，我认为以下是记录该代码行的可接受方式，其中document是命名空间，后跟事件名称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
});

- nunop