How can I mark a parameter as containing a DOM node in JSDoc?

Question

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.

So, how do I mark a parameter as expecting a DOM node?

Answer 1

From jsdoc.app for the @type annotation:

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.

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:

@type {HTMLElement} 

to indicate that the type of something is an HTMLElement (i.e. a DOM node).

My guess as to why this isn't explicitly documented is because the DOM node objects aren't JavaScript built-ins (e.g. String or 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.

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.

Answer 2

If you want something the user can click on, and possibly follow a link to documentation, you can use @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~Node if it is defined in foo.