JSDoc mit AngularJS

Question

Momentan verwenden wir in meinem Projekt JSDoc, wir haben kürzlich mit der Implementierung von Angular begonnen und ich möchte weiterhin JSDoc verwenden, um sicherzustellen, dass sich die gesamte Dokumentation am selben Ort befindet.

Ich habe mir Leute angesehen, die hauptsächlich nur ngDoc verwenden, aber das ist nicht wirklich eine praktikable Option, da wir immer ein separates JavaScript haben und idealerweise alles zusammen haben würde.

Derzeit ist das, was ich habe, aber ich bin nicht in der Lage, Dokumentation für den Lauf() irgendwelche Ideen zu setzen?

Answer 1

ich auch dieses Problem gestoßen sind. Ich schreibe jetzt Dokumentation für AngularJS Codes durch jsdoc Kommentare wie folgt aus:

1.Make eine leere Js-Datei mit folgendem Kommentar:

/** 
    * @namespace angular_module 
    */ 

Dies wird eine separate HTML in der erzeugten Dokumentation für Auflistung erstellen alle Module.

2.In Javascript-Dateien, die alle neuen Winkelmodul definiert, verwenden Sie diese Art von Kommentar

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

Dies wird ein Element in der obigen Auflistung aller angular_modules, sowie die Schaffung einer separaten HTML-Seite hinzu MyModule, weil es eine Klasse ist.

3.Für jeder AngularJS Service, verwenden Sie den folgenden Kommentar:

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

Dies wird ein Element in der MyModule Seite für den Dienst hinzuzufügen. Da es als Funktion hinzugefügt wird, können Sie Dokumentation für Eingabeparameter mit '@param' schreiben und Werte mit '@return' zurückgeben.

4.Wenn ich ziemlich lange Codes in einem Controller oder Direktive von MyModule habe und eine separate HTML-Datei haben möchte, um es zu dokumentieren, werde ich den Controller oder die Direktive als eine Klasse mit dem vollständigen Pfad annotieren. z.B.

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

Auf diese Weise wird MyController als ein Element in der Dokumentationsseite von MyModule aufgelistet.

Dann können wir Codes innerhalb des Controllers als Elementfunktionen von MyController annotieren.

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

Auf diese Weise dieser Dokumentation der Funktion wird in der HTML-Datei von MyController HTML-Seite angezeigt werden. Die durch Punkt getrennte vollständige Pfadzeichenfolge baut die Verbindung auf.

Es gibt drei Arten von Syntaxen für Name:

• Person # sagen // die Instanzmethode namens "sagen."
• Person.say // die statische Methode namens "say."
• Person ~ sagen // die innere Methode mit dem Namen‚sagen.‘

jedoch ein unvollkommener Punkt-Regler als Klasse der Kommentierung ist, dass ein‚neue‘wird vor dem Controller-Namen in dem generierten finden hTML-Dokumentation, weil es als Klassenkonstruktors beschrieben.

1. Außerdem Sie Namespaces, um definieren eine hierarchische Struktur hinzuzufügen. zum Beispiel können Sie einen Namensraum definieren, um alle Controller umfassen

   /** 
   * @namespace MyApp.Controllers 
   */ 
   

, und alle Controller mit MyApp.Controllers voranstellen. Sie können auch Namensräume definieren wie MyApp.Product oder MyApp.Customer usw.

Obwohl nicht perfekt, Ich mag jsdoc mit AngularJS Codes zu dokumentieren, weil

1. Es ist einfach;
2. Die Modul-Controller-Funktionshierarchie wird beibehalten;
3. Und es hält jsdoc's Verdienst, dass es eine durchsuchbare Dokumentationsseite ist.

Ein Tisch Stil jsdoc Sheet:

Insbesondere habe ich den Standard-jsdoc Sheet auf eine Tabelle Stil wie die Java-API-Dokumentation angepasst. Es sieht klarer aus.

In Windows, ersetze ich diese Datei: C:\Users\user1\AppData\Roaming\npm\node_modules\jsdoc\templates\default\static\styles mit dieser Datei https://github.com/gm2008/jsdoc/blob/master/templates/default/static/styles/jsdoc-default.css

Das ist es.

Answer 2

Ich habe den Weg gehen zu schaffen, die Funktionen außerhalb der oben genannten Art und ruft diese Funktionen in solche Dinge wie .run oder Fabriken usw.

/** 
* @author Example <jon.doe@example.com> 
* @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); 
})();