JSDoc

JSDoc est un langage de balisage utilisé pour documenter les codes sources JavaScript. En utilisant des commentaires qui contiennent des informations pour JSDoc, les développeurs peuvent créer la documentation de leurs interfaces de programmation (ou désigné par API en anglais) du code qu'ils créent. Ensuite, ces commentaires seront traités par différents outils (tels que JSDoc pour Node.js), pour produire leur documentation accessible par différents formats, tels que l'HTML ou le Rich Text Format (RTF, ou littéralement « format de texte enrichi »).

Historique

L'exemple le plus vieux^{[citation nécessaire]} en utilisant une syntaxe ressemblante à Javadoc pour un document JavaScript a été réalisé en 1999 avec Netscape/Mozilla (projet Rhino), un système runtime écrit en Java^[1]

La syntaxe de JSDoc et sa sémantique sont similaires à celles de Javadoc, utilisées pour documenter un code écrit en Java. JSDoc est différent de Javadoc car il est spécialisé pour traiter le comportement dynamique du JavaScript.

Les "tags" de JSDoc

Les "tags" les plus populaires de JSDoc sont :

Tag	Description
@author	Nom ou pseudo du développeur
@constructor	Marque une fonction en tant que constructeur
@deprecated	Marque une méthode obsolète
@throws	Documente une exception lancée par une méthode
@exception	Synonyme pour @throws
@exports	Identifie un membre exporté par un module
@param	Documente les paramètres d'une méthode ; le type du paramètre peut être ajouté par des accolades
@private	Signifie qu'un membre est privé
@returns	Documente le retour d'une fonction/méthode
@return	Synonyme de @returns
@see	Documente une association vers un autre objet
@this	Détermine le type de l'objet duquel le mot clé "this" réfère dans une fonction (window par exemple)
@version	Donne la version de la bibliothèque

Exemple

// Note: {} doit contenir le mot en anglais, sauf pour les objets écrits par la développeuse

/**
 * Crée une instance de Cercle
 * 
 * @constructor
 * @this {Cercle}
 * @param {number} r Le rayon désiré du cercle.
 */
 
function Cercle(r) {
    /** @private */ this.rayon = r;
    /** @private */ this.circonference = 2 * Math.PI * r;
};

/**
 * Crée un nouveau cercle à partir du diamètre
 * 
 * @param {number} d Le diamètre désiré du cercle
 * @return {Cercle} Le nouvel objet Cercle
 */

Cercle.aPartirDeDiametre = function (d) {
    return new Cercle(d / 2);
};

/**
 * Calcule la circonférence du Cercle.
 * 
 * @deprecated
 * @this {Cercle}
 * @return {number} La circonférence du cercle
 */

Cercle.prototype.calculerCirconference = function() {
    return 2 * Math.PI * this.rayon;
};

/**
 * Retourne la circonférence du Cercle.
 * 
 * @this {Cercle}
 * @return {number} La circonférence du Cercle.
 */
Cercle.prototype.getCirconference = function() {
    return this.circonference;
};

/**
 * Crée un texte représentant le Cercle.
 * 
 * @override
 * @this {Cercle}
 * @return {string} Une représentation lisible du Cercle.
 */
Cercle.prototype.toString = function() {
    return "Un objet Cercle avec un rayon de " + this.rayon + ".";
};

JSDoc en utilisation

• Le "Closure Linter" et son "Closure Compiler". Son dernier extrait les types d'informations pour optimiser sa sortie JavaScript.
• L'éditeur populaire Sublime Text qui supporte JSDoc à travers le DocBlockr ou DoxyDoxygen plugin.
• La syntaxe de JSDoc a été décrite dans le livre "Apress Book - Foundations of Ajax" (ISBN 1-59059-582-3).
• IntelliJ IDEA, NetBeans et RubyMine comprennent la syntaxe JSDoc.
• L'Eclipse IDE a des extensions qui comprennent la syntaxe JSDoc. Aptana Studio (basé sur Eclipse) supporte ScriptDoc, et les fichiers JavaScript inclus sont commentés en ScriptDoc.
• Mozile, l'Editeur Inline de Mozilla utilises JSDoc.
• Le Framework Helma utilise JSDoc.
• La documentation de SproutCore a été générée avec JSDoc.
• Microsoft Visual Studio, WebStorm et plusieurs autres IDE ou éditeurs de textes offrent l'autocomplétion du code et d'autres aides sur la création des commentaires JSDoc.
• L'éditeur open source Atom supporte JSDoc via le plugin atom-easy-jsdoc.

À voir aussi

• Comparaison des générateurs de documentation [EN]