javascript 如何在 JSDoc 中将参数标记为包含 DOM 节点？
声明：本页面是StackOverFlow热门问题的中英对照翻译，遵循CC BY-SA 4.0协议，如果您需要使用它，必须同样遵循CC BY-SA许可，注明原文地址和作者信息，同时你必须将它归于原作者（不是我）：StackOverFlow
原文地址: http://stackoverflow.com/questions/21489044/
Warning: these are provided under cc-by-sa 4.0 license. You are free to use/share it, But you must attribute it to the original authors (not me):
StackOverFlow
How can I mark a parameter as containing a DOM node in JSDoc?
提问by cdeszaq
I want to indicate that a parameter should be a DOM node, but I can't seem to find any information about how to indicate that with JSDoc. I could just use {Object}, but that is rather ugly. I would much rather have something like {Node}or {DOMNode}, but I can't find any examples to point me in that direction.
我想表明一个参数应该是一个 DOM 节点，但我似乎找不到任何关于如何用 JSDoc 来表明它的信息。我可以只使用{Object}，但这相当丑陋。我更愿意有类似{Node}或 的东西{DOMNode}，但我找不到任何例子来指出我的方向。
So, how do I mark a parameter as expecting a DOM node?
那么，如何将参数标记为期望 DOM 节点？
回答by ajp15243
From jsdoc.appfor the @typeannotation:
来自jsdoc.app的@type注释：
A type expression can include the JSDoc namepath to a symbol (for example, myNamespace.MyClass); a built-in JavaScript type (for example, string); or a combination of these. You can use any Google Closure Compiler type expression, as well as several other formats that are specific to JSDoc.
[...]
Each type is specified by providing a type expression, using one of the formats described below. Where appropriate, JSDoc will automatically create links to the documentation for other symbols. For example, @type {MyClass} will link to the MyClass documentation if that symbol has been documented.
类型表达式可以包含符号的 JSDoc 名称路径（例如，myNamespace.MyClass）；一个内置的 JavaScript 类型（例如，字符串）；或这些的组合。您可以使用任何 Google Closure Compiler 类型表达式，以及特定于 JSDoc 的其他几种格式。
[...]
每种类型都通过使用以下描述的格式之一提供类型表达式来指定。在适当的情况下，JSDoc 将自动创建指向其他符号文档的链接。例如，如果该符号已被记录，@type {MyClass} 将链接到 MyClass 文档。
So you can link to symbols. HTMLElement(and inheriting objects like HTMLImageElement) are symbols. Therefore, if you follow the spec, you should be allowed to do:
所以你可以链接到符号。HTMLElement（和继承对象如HTMLImageElement）是符号。因此，如果你遵循规范，你应该被允许做：
@type {HTMLElement}
to indicate that the type of something is an HTMLElement(i.e. a DOM node).
表示某物的类型是一个HTMLElement（即一个 DOM 节点）。
My guess as to why this isn't explicitly documented is because the DOM node objects aren't JavaScript built-ins (e.g. Stringor Number). They are added by the client browser, so they are technically like any other symbol that you and I could make (being implemented with native browser code aside), as far as the JS language spec is concerned.
我对为什么没有明确记录的原因的猜测是因为 DOM 节点对象不是 JavaScript 内置对象（例如String或Number）。它们是由客户端浏览器添加的，因此就 JS 语言规范而言，它们在技术上就像您和我可以制作的任何其他符号（除了本机浏览器代码之外）。
While we haven't gotten to the stage of actually compiling our documentation (that's a separate story), which would confirm if the above is truly accepted by JSDoc, this is how we interpret and follow this particular concept where I work, and our standard IDE (IntelliJ) accepts it.
虽然我们还没有进入实际编译我们的文档的阶段（这是一个单独的故事），这将确认上述内容是否真的被 JSDoc 接受，这就是我们在我工作的地方解释和遵循这个特定概念的方式，以及我们的标准IDE (IntelliJ) 接受它。
回答by Louis
If you want something the user can click on, and possibly follow a link to documentation, you can use @external:
如果您想要用户可以单击的内容，并可能点击文档链接，您可以使用@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) {
}
I don't bother with this and just mark such parameters with {Node}. All my code is in modules so the types that I define all begin with module:. So even if I had a class named Node, it would appear as module:foo~Nodeif it is defined in foo.
我不介意这个，只是用{Node}. 我所有的代码都在模块中，所以我定义的类型都以module:. 因此，即使我有一个名为 的类Node，它看起来也module:foo~Node好像是在foo.
