33

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

私は主に ngDoc を使用するように言っているだけの人を調べましたが、これは実際には実行可能なオプションではありません。常に個別の JavaScript を使用し、理想的にはすべてを一緒に使用するためです。

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

    /**
     * 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() のドキュメントを配置することはできませんか?

4

2 に答える 2

68

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

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

 /**
  * @namespace angular_module
  */

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

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

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

これにより、上記のすべての angular_modules のリストにアイテムが追加され、MyModule はクラスであるため、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 ドキュメントでコントローラー名の前に "new" が見つかることです。

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

    /**
 * @namespace MyApp.Controllers
 */

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

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

  1. 簡単です;
  2. モジュール - コントローラ - 関数の階層は維持されます。
  3. そして閲覧可能なドキュメンテーションサイトというjsdocのメリットはそのままに。

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

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

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

それでおしまい。

于 2014-06-13T15:21:51.760 に答える