javascript - datatype - jsdoc tutorial

¿Cómo puedo marcar un parámetro como que contiene un nodo DOM en JSDoc?

Question

Quiero indicar que un parámetro debe ser un nodo DOM, pero parece que no puedo encontrar información sobre cómo indicar eso con JSDoc. Podría usar {Object} , pero eso es bastante feo. Preferiría tener algo como {Node} o {DOMNode} , pero no puedo encontrar ningún ejemplo para señalarme en esa dirección.

Entonces, ¿cómo marque un parámetro como esperando un nodo DOM?

Answer 1

De UseJSDoc.org para la anotación @type :

Una expresión de tipo puede incluir la ruta de acceso JSDoc en un símbolo (por ejemplo, myNamespace.MyClass); un tipo de JavaScript incorporado (por ejemplo, cadena); o una combinación de estos. Puede usar cualquier expresión de tipo de compilador de cierre de Google, así como otros formatos específicos de JSDoc.

[...]

Cada tipo se especifica al proporcionar una expresión de tipo, utilizando uno de los formatos que se describen a continuación. Cuando corresponda, JSDoc creará automáticamente enlaces a la documentación de otros símbolos. Por ejemplo, @type {MyClass} enlazará a la documentación de MyClass si ese símbolo ha sido documentado.

Entonces puedes enlazar a símbolos. HTMLElement (y heredar objetos como HTMLImageElement ) son símbolos. Por lo tanto, si sigue las especificaciones, se le debe permitir hacer:

@type {HTMLElement}

para indicar que el tipo de algo es un HTMLElement (es decir, un nodo DOM).

Mi suposición de por qué esto no está documentado explícitamente se debe a que los objetos del nodo DOM no son complementos de JavaScript (por ejemplo, String o Number ). Se agregan mediante el navegador del cliente, por lo que son técnicamente similares a cualquier otro símbolo que usted y yo pudiéramos tener (implementados con el código del navegador nativo), en lo que respecta a la especificación del lenguaje JS.

Si bien no hemos llegado a la etapa de recopilar realmente nuestra documentación (que es una historia separada), que confirmaría si lo anterior es realmente aceptado por JSDoc, así es como interpretamos y seguimos este concepto particular donde trabajo, y nuestro estándar IDE (IntelliJ) lo acepta.

Answer 2

Si desea algo en lo que el usuario pueda hacer clic y, posiblemente, siga un enlace a la documentación, puede usar @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) {
}

No me molesto con esto y simplemente marco esos parámetros con {Node} . Todo mi código está en módulos, por lo que los tipos que defino todos comienzan con el module: Así que incluso si tuviera una clase llamada Node , aparecería como module:foo~Node si está definido en foo .