JSDoc

Un article de Wikipédia, l'encyclopédie libre.
Sauter à la navigation Sauter à la recherche

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 leur documentation de leurs interface 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 (tel que JSDoc pour Node.js), pour produire leur documentation accessible par différents formats, tel que l'HTML ou le Rich Text Format (RTF, ou littéralement « format de texte enrichi »).

Historique[modifier | modifier le code]

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[modifier | modifier le code]

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é
@return Documente le retour d'une fonction/méthode
@returns Synonyme de @return
@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[modifier | modifier le code]

// Note: {} doit contenir le mot en anglais, sauf pour les objets écrits par le dev.

/**
 * 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[modifier | modifier le code]

  • 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 bien é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. [1]
  • 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[modifier | modifier le code]

Références[modifier | modifier le code]

  1. (en) Mozilla project, « jsdoc.js »,

Liens externes[modifier | modifier le code]