web-dev-qa-db-fra.com

Comment puis-je marquer un paramètre comme contenant un nœud DOM dans JSDoc?

Je veux indiquer qu'un paramètre doit être un nœud DOM, mais je n'arrive pas à trouver d'informations sur la façon d'indiquer cela avec JSDoc. Je pourrais simplement utiliser {Object}, mais c'est plutôt moche. Je préférerais de loin quelque chose comme {Node} ou {DOMNode}, mais je ne trouve aucun exemple pour m'orienter dans cette direction.

Alors, comment puis-je marquer un paramètre comme attendant un nœud DOM?

javascriptdomjsdoc
36
cdeszaq

De jsdoc.app pour le @type annotation:

Une expression de type peut inclure le chemin de nom JSDoc vers un symbole (par exemple, myNamespace.MyClass); un type JavaScript intégré (par exemple, chaîne); ou une combinaison de ceux-ci. Vous pouvez utiliser n'importe quelle expression de type Google Closure Compiler, ainsi que plusieurs autres formats spécifiques à JSDoc.

[...]

Chaque type est spécifié en fournissant une expression de type, en utilisant l'un des formats décrits ci-dessous. Le cas échéant, JSDoc créera automatiquement des liens vers la documentation d'autres symboles. Par exemple, @type {MyClass} sera lié à la documentation MyClass si ce symbole a été documenté.

Vous pouvez donc créer un lien vers des symboles. HTMLElement (et les objets hérités comme HTMLImageElement ) sont des symboles. Par conséquent, si vous suivez les spécifications, vous devriez être autorisé à faire:

@type {HTMLElement}

pour indiquer que le type de quelque chose est un HTMLElement (c'est-à-dire un nœud DOM).

Je suppose que cela n'est pas explicitement documenté parce que les objets de noeud DOM ne sont pas des composants JavaScript intégrés (par exemple String ou Number). Ils sont ajoutés par le navigateur client, ils sont donc techniquement comme tout autre symbole que vous et moi pourrions créer (mis en œuvre avec le code du navigateur natif à part), en ce qui concerne les spécifications du langage JS.

Bien que nous ne soyons pas arrivés au stade de la compilation de notre documentation (c'est une histoire distincte), ce qui confirmerait si ce qui précède est vraiment accepté par JSDoc, voici comment nous interprétons et suivons ce concept particulier où je travaille, et notre norme IDE (IntelliJ) l'accepte.

49
ajp15243

Si vous voulez quelque chose sur lequel l'utilisateur peut cliquer et éventuellement suivre un lien vers la documentation, vous pouvez utiliser @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) {
}

Je ne me soucie pas de cela et je marque simplement ces paramètres avec {Node}. Tout mon code est dans des modules, donc les types que je définis commencent tous par module:. Donc, même si j'avais une classe nommée Node, elle apparaîtrait comme module:foo~Node s'il est défini dans foo.

8
Louis