如何在 JSDoc 中将参数标记为包含 DOM 节点？答案

【问题标题】：How can I mark a parameter as containing a DOM node in JSDoc?如何在 JSDoc 中将参数标记为包含 DOM 节点？
【发布时间】：2014-02-24 16:15:32
【问题描述】：

我想指出一个参数应该是一个 DOM 节点，但我似乎找不到任何关于如何使用 JSDoc 来指示它的信息。我可以只使用{Object}，但这很丑陋。我更喜欢{Node} 或{DOMNode} 之类的东西，但我找不到任何例子来指出我的方向。

那么，如何将参数标记为期望 DOM 节点？

【问题讨论】：

标签： javascript dom jsdoc

【解决方案1】：

来自jsdoc.app 的@type 注释：

类型表达式可以包含符号的 JSDoc 名称路径（例如，myNamespace.MyClass）；内置的 JavaScript 类型（例如，字符串）；或这些的组合。您可以使用任何 Google Closure Compiler 类型表达式，以及其他几种特定于 JSDoc 的格式。

[...]

每种类型都通过提供一个类型表达式来指定，使用下面描述的一种格式。在适当的情况下，JSDoc 将自动创建指向其他符号文档的链接。例如，@type {MyClass} 将链接到 MyClass 文档（如果该符号已记录）。

因此您可以链接到符号。 HTMLElement（以及像HTMLImageElement 这样的继承对象）是符号。因此，如果你遵循规范，你应该被允许这样做：

@type {HTMLElement}

表示某事物的类型是HTMLElement（即 DOM 节点）。

我猜测为什么没有明确记录是因为 DOM 节点对象不是 JavaScript 内置的（例如 String 或 Number）。它们是由客户端浏览器添加的，因此就 JS 语言规范而言，它们在技术上与您和我可以制作的任何其他符号一样（除了使用本机浏览器代码实现）。

虽然我们还没有到实际编译我们的文档的阶段（这是一个单独的故事），这将确认上述内容是否真正被 JSDoc 接受，这就是我们解释和遵循我工作的这个特定概念的方式，我们的标准 IDE (IntelliJ) 接受它。

【讨论】：

【解决方案2】：

如果您想要用户可以点击的内容，并可能点击文档链接，您可以使用@external：

/**
 * A node in the DOM tree.
 *
 * @external Node
 * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/Node Node}
 */

/**
 * @param {external:Node} node
 */
function foo(node) {
}

我不关心这个，只是用{Node}标记这些参数。我所有的代码都在模块中，所以我定义的类型都以module: 开头。所以即使我有一个名为Node 的类，如果它在foo 中定义，它也会显示为module:foo~Node。

【讨论】：

【解决方案3】：

这对我来说效果很好，所以我得到了 vscode 的帮助

/**
* Represents a getElement.
* @param {string} selector - The selector html.
* @returns {HTMLElement}
*/
const getElement = (selector) => document.querySelector(selector);

enter image description here

【讨论】：