Question

我想指出一个参数应该是一个DOM节点，但我似乎无法找到有关如何用JSDoc指示的信息。我可以使用{Object}，但这很难看。我更愿意拥有像{Node}或{DOMNode}这样的东西，但我找不到任何一个例子来指引我朝这个方向发展。

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

Answer 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）接受它。

Answer 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的类，如果它在module:foo~Node中定义，它也会显示为foo。

Answer 3

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

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

enter image description here

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

3 个答案: