Documenter son code Angular avec angular-jsdoc

Vous êtes fatigué(e) de lire et relire les lignes de code du dernier projet en cours  ? Vous en avez marre de chercher pendant des heures le proto d’une fonction ? Vous vous apprêtez à écrire un joli document redondant sur votre tout dernier service Angular  ?

Arrêtez tout, angular-jsdoc is what you need !

Ce plugin npm, basé sur jsdoc,  un générateur de documentation de code JavaScript, vous permet en quelques lignes de décrire services, directives, contrôleurs et leurs fonctions/méthodes respectives.

Une petite commande gulp/grunt et hop, vous voilà avec une magnifique doc au format web !

Installation

Dans un premier temps, allez faire un tour sur le repo GitHub du projet, quand on installe un nouveau module c’est quand même la base.

https://github.com/allenhwkim/angular-jsdoc

C’est bon, vous avez tout lu ? Alors c’est parti…

On commence par installer jsdoc et angular-jsdoc dans le répertoire de notre projet (nécessite au préalable npm).

npm install jsdoc angular-jsdoc --save-dev

(L’option save-dev permet de sauvegarder le plugin uniquement pour l’environnement dev, au moment de la mise en production il ne sera pas nécessaire d’importer les sources).

On va maintenant définir une nouvelle tâche gulp pour générer nos docs, c’est aussi possible avec grunt, ou directement en ligne de commande, si vous n’aimez pas gulp les instructions grunt/ligne de commande sont consultables sur le repo GitHub.

On va générer la doc dans /docs, gulp n’ayant pas les droits nécéssaires pour créer le répertoire tout seul comme un grand, il nous faut le créer à la main.

mkdir docs

Pour faire fonctionner notre usine à gaz nous allons avoir besoin du module gulp-shell (nécessaire pour que gulp puisse interpréter des commandes shell).

npm install gulp-shell --save-dev

On importe le module dans le fichier gulpfile.js :

var shell = require('gulp-shell');

Il faut maintenant déclarer la nouvelle tâche gulp. Pour cela, toujours dans le fichier gulpfile.js, rajoutez les lignes suivantes :

gulp.task('docs', shell.task([
    'node_modules/jsdoc/jsdoc.js ' +
    '-c node_modules/angular-jsdoc/common/conf.json ' + // config file
    '-t node_modules/angular-jsdoc/angular-template ' + // template file
    '-d docs ' + // output directory
    './README.md ' + // to include README.md as index contents
    '-r dev/js dev/config dev/services dev/controllers dev/directives dev/filters ' // source code directories
]));

La dernière ligne permet de définir les répertoires de vos sources, angular-jsdoc en a besoin pour chercher des commentaires, il faudra donc lister les répertoires de votre projet Angular, dans notre cas nous avons :

• app
  • dev
    • js
    • config
    • controllers
    • directives
    • filters

Vous aurez donc peut-être besoin de la modifier si votre organisation diffère.

Et nous voilà enfin prêt à entrer dans le vif du sujet !

Commenter son code

Premier exemple: un contrôleur:

(function () {

    'use strict';

    /**
    * @memberof app
    * @ngdoc controllers
    * @name loginController
    * @param {object} $scope
    * @param {object} userService used to interact with users
    * @param {object} Notification
    * @param {object} $state
    * @param {object} config app configuration
    * @description
    *    Login controller.
    */
    angular
    .module('app.controllers')
    .controller('loginController', ['$scope', 'userService', 'Notification', '$state', 'config', loginController]);

    function loginController($scope, userService, Notification, $state, config) {

        // ...

    }

})();

Comment ça marche ? Alors c’est assez simple, juste au dessus de la déclaration de votre contrôleur, ou n’importe où si ça vous chante, vous allez décrire votre contrôleur dans un commentaire spécial, en doublant le caractère *.

Vous déclarez le parent, à savoir le module app, à l’aide du keyword @memberof, ensuite il vous faut déclarer le module, à l’aide de @ngdoc nom_du_module (controllers dans notre cas).

Vous pouvez ensuite déclarer les paramètres (les injections) à l’aide du mot clé @param, sous la forme suivante:

@param {type}  name (description)

Pour finir on peut ajouter une description à notre contrôleur via le mot clé @description.

On peut appliquer exactement le même principe pour services, directives ou encore providers, il suffira de déclarer le bon module via @ngdoc.

Facile non ? Intéressons nous maintenant aux fonctions et méthodes.

/**
* @memberof loginController
* @param {string} email
* @returns {boolean}
*/
$scope.validEmail = function(email) {
    var re = /^(([^<>()\[\]\\.,;:\s@"]+(\.[^<>()\[\]\\.,;:\s@"]+)*)|(".+"))@((\[[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}])|(([a-zA-Z\-0-9]+\.)+[a-zA-Z]{2,}))$/;
    return !email || re.test(email);
};

Ici, on utilise exactement le même principe, on a simplement indiqué une valeur de retour à l’aide du key word @returns, ne pas oublier d’indiquer qu’il s’agit d’une méthode du contrôleur en pensant bien à spécifier @memberof.

Générer la doc

Une simple ligne de commande, et bingo, le tour est joué.

gulp docs

On peut ouvrir le fichier index.html se trouvant dans /docs à l’aide d’un navigateur, selon notre conf, c’est le fichier README.md qui sert de page d’accueil au site web. On sélectionne le module qui nous intéresse, et voilà le rendu :

Vous pouvez donc depuis cette page consulter toutes les informations renseignées sur vos modules et consulter directement la source si besoin.

On aura vu ici les mots clés de bases, mais sachez que d’autres sont disponibles, pour cela allez voir la doc angular-jsdoc et jsdoc (http://usejsdoc.org/).

Conclusion

Angular-jsdoc de par sa simplicité et son efficacité, son utilisation intuitive et son rendu web épuré offre une solution complète de normalisation de la documentation des projets professionnels. À l’heure des APIs Web, une bonne documentation de vos projets est un plus, tout bon dev saura choisir l’outil adapté, angular-jsdoc répondant parfaitement à la situation, il serait dommage de s’en passer.