Pourquoi JSDoc plutôt que TypeScript ?

Parce que le fichier reste du JavaScript. Avec `checkJs` activé, le compilateur TypeScript lit ces typedefs et vous rend les mêmes erreurs dans l’éditeur, sans build, sans extension `.ts`, sans transpilation. Pour un script Node ou une petite bibliothèque livrée telle quelle, c’est tout le bénéfice des types et rien de leur coût.

Comment utiliser le typedef engendré ?

Référencez-le par son nom : `/** @type {Root} */` sur une variable, ou `@param {Root} payload` sur une fonction. Si les typedefs vivent dans un autre fichier, importez-les avec `/** @typedef {import("./types.js").Root} Root */` — l’éditeur les résout de la même façon.

JSON en JSDoc — l’autocomplétion en JS simple

Transformez un échantillon JSON en typedefs JSDoc. Chaque objet devient un @typedef nommé que l’éditeur lit, en JavaScript simple, sans étape de build.

Instantané Privé Zéro cookie

Nom racine

Entrée JSON

Sortie JSDoc

Ce que fait cet outil

Un échantillon JSON devient des typedefs JSDoc, un bloc par objet.

{ "id": 1, "name": "Ada", "address": { "city": "Paris" } }

/**
 * @typedef {Object} Root
 * @property {number} id
 * @property {string} name
 * @property {Address} address
 */

/**
 * @typedef {Object} Address
 * @property {string} city
 */

Posez-les en tête d’un fichier .js et chaque @type {Root} de ce fichier est vérifié — par votre éditeur, et par tsc --checkJs si vous le lancez.

Une liste à la racine est nommée elle aussi

/**
 * @typedef {Array<UsersItem>} Users
 */

Ce bloc manquait : un échantillon en tableau ne produisait que le typedef de l’élément, et le nom racine que vous aviez réglé n’allait nulle part. C’était un vrai défaut, trouvé en écrivant cette page et corrigé.

Les tableaux s’écrivent toujours Array<…> plutôt que …[]. Les deux sont valides ; la forme longue reste lisible quand le type de l’élément est une union ou un *.

Une clé qui n’est pas un identifiant

{ "content-type": "text/html" }

 * @property {string} "content-type"

Les guillemets gardent la clé lisible, et ils ne sont pas du JSDoc standard : il n’existe pas de syntaxe pour un nom de propriété qui n’est pas un identifiant valide. C’est dit plutôt que tu : rien dans la sortie ne vous préviendra, et un éditeur peut simplement ignorer cette ligne. Une clé pareille gagne à être renommée à la source.

Ce qu’un échantillon ne peut pas décider

Chaque propriété est documentée comme présente, parce que c’est ce que le document montrait. JSDoc note une propriété optionnelle @property {string} [name] et une propriété nullable {?string} — deux retouches que l’on fait en connaissant l’API, pas des faits contenus dans une charge unique.

Une valeur inconnue devient *, le « n’importe quel type » de JSDoc. Il apparaît là où l’échantillon se tait : un tableau vide donne Array<*>.

Confidentiel par conception

Tout s’exécute localement dans votre navigateur en JavaScript. Vos données ne sont jamais envoyées sur un serveur, ce qui rend l’outil sûr pour des contenus sensibles, et il fonctionne hors ligne.

Questions fréquentes

Pourquoi JSDoc plutôt que TypeScript ?: Parce que le fichier reste du JavaScript. Avec `checkJs` activé, le compilateur TypeScript lit ces typedefs et vous rend les mêmes erreurs dans l’éditeur, sans build, sans extension `.ts`, sans transpilation. Pour un script Node ou une petite bibliothèque livrée telle quelle, c’est tout le bénéfice des types et rien de leur coût.
Une clé avec un tiret est sortie entre guillemets. Est-ce valide ?: Pas vraiment, et c’est la limite honnête de cette sortie. `@property {string} "content-type"` garde la clé lisible, mais JSDoc n’a pas de syntaxe pour un nom de propriété qui n’est pas un identifiant : les guillemets ne relèvent d’aucune spécification. Mieux vaut renommer cette clé à la source, ou la documenter en prose à côté.
Comment utiliser le typedef engendré ?: Référencez-le par son nom : `/** @type {Root} */` sur une variable, ou `@param {Root} payload` sur une fonction. Si les typedefs vivent dans un autre fichier, importez-les avec `/** @typedef {import("./types.js").Root} Root */` — l’éditeur les résout de la même façon.