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[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é |
| @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[modifier | modifier le code]
// 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[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 é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]
- (en) Mozilla project, « jsdoc.js »,
Liens externes[modifier | modifier le code]
- Le lien officiel de JSDoc, pour des tutoriels et documentations
- Le GitHub officiel de JSDoc, pour du code à jour
- "Annotating JavaScript for the Closure Compiler", La documentation de Closure Tools, Google Developer website.
