web-dev-qa-db-fra.com

JSDoc avec AngularJS

Actuellement, dans mon projet, nous utilisons JSDoc, nous avons récemment commencé à implémenter Angular et je veux continuer à utiliser JSDoc pour m'assurer que toute la documentation est au même endroit.

J'ai jeté un coup d'œil aux gens qui disent simplement d'utiliser ngDoc, mais ce n'est pas vraiment une option viable car nous aurons toujours un JavaScript séparé et, idéalement, j'aurais tout ensemble.

/**
 * @author Example <[email protected]>
 * @copyright 2014 Example Ltd. All rights reserved.
 */
(function () {
    window.example = window.example || {};
    /**
     * Example Namespace
     * @memberOf example
     * @namespace example.angular
     */
    window.example.angular = window.example.angular || {};
    var exAngular = window.example.angular;

    /**
     * A Example Angular Bootstrap Module
     * @module exampleAngularBootstrap
     */
    exAngular.bootstrap = angular.module('exampleAngularBootstrap', [
            'ngRoute',
            'ngResource',
            'ngCookies'
        ])
        .run(function ($http, $cookies) {
            $http.defaults.headers.post['X-CSRFToken'] = $cookies.csrftoken;
            $http.defaults.headers.common['X-CSRFToken'] = $cookies.csrftoken;
        });
})();

Actuellement, c'est ce que j'ai, mais je ne peux pas mettre de documentation pour la course () des idées?

angularjsjsdocjsdoc3
31
Nick White

J'ai également rencontré ce problème. J'écris maintenant de la documentation pour les codes angularjs à travers des commentaires jsdoc comme ceci:

1.Faites un fichier .js vierge avec le commentaire suivant:

 /**
  * @namespace angular_module
  */

Cela créera un html séparé dans la documentation générée pour lister tous les modules.

Dans les fichiers javascript qui définissent tout nouveau module angular, utilisez ce type de commentaire

 /**
  * @class angular_module.MyModule
  * @memberOf angular_module    
  */

Cela ajoutera un élément dans la liste ci-dessus de tous les modules angulaires, ainsi que la création d'une page html distincte pour MyModule, car il s'agit d'une classe.

3.Pour chaque service angularjs, utilisez le commentaire suivant:

 /**
  * @function myService
  * @memberOf angular_module.MyModule
  * @description This is an angularjs service.
  */

Cela ajoutera un élément dans la page MyModule pour le service. Parce qu'il est ajouté en tant que fonction, vous pouvez écrire de la documentation pour les paramètres d'entrée en utilisant '@param' et renvoyer des valeurs en utilisant '@return'.

4.Si j'ai des codes assez longs dans un contrôleur ou une directive de MyModule et que je veux avoir un fichier html séparé pour le documenter, j'annoterai le contrôleur ou la directive en tant que classe en utilisant le chemin complet. par exemple.

 /**
  * @class angular_module.MyModule.MyController
  */

De cette façon, MyController sera répertorié comme un élément dans la page de documentation de MyModule.

Ensuite, nous pouvons annoter des codes dans le contrôleur en tant que fonctions membres de MyController.

 /**
  * @name $scope.aScopeFunction
  * @function
  * @memberOf angular_module.MyModule.MyController
  * @description
  */

De cette façon, la documentation de cette fonction apparaîtra dans le fichier html de la page html de MyController. La chaîne de chemin d'accès complète séparée par des points établit la connexion.

Il existe trois types de syntaxes pour le chemin de nom:

  • Personne # say // la méthode d'instance nommée "say".
  • Person.say // la méthode statique nommée "say".
  • Personne ~ say // la méthode interne nommée "say".

Cependant, un point imparfait de commenter le contrôleur en tant que classe est qu'un "nouveau" sera trouvé avant le nom du contrôleur dans la documentation HTML générée car il est décrit comme constructeur de classe.

  1. De plus, vous pouvez définir des espaces de noms afin d'ajouter une structure hiérarchique. Par exemple, vous pouvez définir un espace de noms pour inclure tous les contrôleurs

    /**
 * @namespace MyApp.Controllers
 */

et préfixez tous les contrôleurs avec MyApp.Controllers. Vous pouvez également définir des espaces de noms comme MyApp.Product ou MyApp.Customer etc.

Bien que pas parfait, j'aime utiliser jsdoc pour documenter les codes angularjs car

  1. C'est simple;
  2. La hiérarchie module-contrôleur-fonction est conservée;
  3. Et il conserve le mérite de jsdoc d'être un site de documentation consultable.

Une feuille de style jsdoc de style de table:

En particulier, j'ai adapté la feuille de style jsdoc par défaut à un style de tableau comme la documentation de l'API Java. Elle semble plus claire.

Sous Windows, je remplace ce fichier: C:\Users\user1\AppData\Roaming\npm\node_modules\jsdoc\templates\default\static\styles avec ce fichier https://github.com/gm2008/jsdoc/blob/master/templates/default/static/styles/jsdoc-default.css

C'est ça.

67
gm2008

J'ai dû suivre la voie de la création des fonctions en dehors du type ci-dessus et appeler ces fonctions dans des choses telles que .run ou usines, etc.

/**
 * @author Example <[email protected]>
 * @copyright 2014 Example Ltd. All rights reserved.
 */
(function () {
    window.example = window.example || {};
    /**
     * Example Namespace
     * @memberOf example
     * @namespace example.angular
     */
    window.example.angular = window.example.angular || {};
    var exAngular = window.example.angular;
    /**
     * My example bootstrap run function
     * @param  {object} $http    {@link http://docs.angularjs.org/api/ng.$http}
     * @param  {[type]} $cookies {@link http://docs.angularjs.org/api/ngCookies.$cookies}
     */
    var runFunction = function ($http, $cookies) {
        $http.defaults.headers.post['X-CSRFToken'] = $cookies.csrftoken;
        $http.defaults.headers.common['X-CSRFToken'] = $cookies.csrftoken;
    };

    /**
     * A Example Angular Bootstrap Module
     * @memberOf example.angular
     * @namespace example.angular.bootstrap
     * @function bootstrap
     * @example
     *     &lt;div ng-app="exampleAngularBootstrap"&gt;
     *         &lt;div ng-view&gt;&lt;/div&gt;
     *     &lt;/div&gt;  
     */
    exAngular.bootstrap = angular.module('exampleAngularBootstrap', [
            'ngRoute',
            'ngResource',
            'ngCookies'
        ])
        .run(runFunction);
})();
4
Nick White