web-dev-qa-db-ja.com

AngularJSを使用したJSDoc

現在、私のプロジェクトではJSDocを使用していますが、最近Angularの実装を開始しました。JSDocを引き続き使用して、すべてのドキュメントが同じ場所に収まるようにします。

私は主にngDocを使用するように言っている人を見てきましたが、これは常に独立したJavaScriptを持ち、理想的にはすべてを一緒に持っているので、これは現実的な選択肢ではありません。

/**
 * @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;
        });
})();

現在、これは私が持っているものですが、run（）のドキュメントを置くことはできませんか？

angularjsjsdocjsdoc3
31
Nick White

私もこの問題に遭遇しました。私は今、このようなjsdocコメントを通じてangularjsコードのドキュメントを書いています：

1.次のコメントを付けて空の.jsファイルを作成します。

 /**
  * @namespace angular_module
  */

これにより、すべてのモジュールを一覧表示するために、生成されたドキュメントに別個のhtmlが作成されます。

2.新しいangularモジュールを定義するjavascriptファイルでは、この種のコメントを使用します

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

これは、クラスであるため、上記のすべてのangle_modulesのリストにアイテムを追加し、MyModule用に別のhtmlページを作成します。

3.各angularjsサービスについて、次のコメントを使用します：

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

これにより、サービスのMyModuleページにアイテムが追加されます。関数として追加されるため、「@ param」を使用して入力パラメーターのドキュメントを作成し、「@ return」を使用して値を返すことができます。

4. MyModuleのコントローラーまたはディレクティブに非常に長いコードがあり、それを文書化するための別個のhtmlファイルが必要な場合、コントローラーまたはディレクティブにフルパスを使用するクラスとして注釈を付けます。例えば.

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

このように、MyControllerはMyModuleのドキュメントページに1つのアイテムとしてリストされます。

次に、コントローラー内のコードにMyControllerのメンバー関数として注釈を付けます。

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

このようにして、この関数のドキュメントはMyControllerのhtmlページのhtmlファイルに表示されます。ドット区切りのフルパス文字列により接続が構築されます。

Namepathには3種類の構文があります。

  • Person＃say //「say」という名前のインスタンスメソッド
  • Person.say //「say」という名前の静的メソッド
  • Person〜say //「say」という名前の内部メソッド

ただし、コントローラをクラスとしてコメントすることの不完全な点の1つは、クラスコンストラクタとして記述されているため、生成されたhtmlドキュメントでコントローラ名の前に「新しい」が見つかるということです。

  1. さらに、階層構造を追加するために名前空間を定義できます。たとえば、名前空間を定義してすべてのコントローラーを含めることができます

    /**
 * @namespace MyApp.Controllers
 */

、すべてのコントローラーの前にMyApp.Controllersを付けます。 MyApp.ProductやMyApp.Customerなどの名前空間を定義することもできます。

完全ではありませんが、私はjsdocを使用してangularjsコードを文書化するのが好きです

  1. それは単純だ;
  2. モジュール、コントローラー、機能の階層は保持されます。
  3. また、閲覧可能なドキュメントサイトであるというjsdocのメリットを維持しています。

テーブルスタイルのjsdocスタイルシート：

特に、デフォルトのjsdocスタイルシートをJava APIドキュメントのような表スタイルに適合させました。より明確に見えます。

Windowsでは、このファイルをC:\Users\user1\AppData\Roaming\npm\node_modules\jsdoc\templates\default\static\stylesに置き換えます https://github.com/gm2008/jsdoc/blob/master/templates/default/static/styles/jsdoc-default.css

それでおしまい。

67
gm2008

上記のタイプ以外の関数を作成し、それらの関数を.runやfactoriesなどで呼び出すというルートをたどる必要がありました。

/**
 * @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