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

Question

我想指出一个参数应该是一个DOM节点,但我似乎无法找到有关如何用JSDoc指示的信息.我可以使用{Object},但这很难看.我宁愿有类似{Node}或{DOMNode},但我找不到任何的例子指向我这个方向努力.

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

Answer 1

从UseJSDoc.org获取@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.