2

angular アプリケーションのドキュメントを追加することを検討していますが、これまでの調査結果から、JSDoc が一般的な選択肢のようです。

私は現在、モジュールと関連するコントローラー\ディレクティブ\サービス\などに続く構造で生成するドキュメントを取得するのに苦労しています。

最初に、私が取り組んでいるアプリケーションにある種類のコードのサンプルを次に示します。

angular.module('app', [
  'app.core',
  'app.features'
]);


(function() {
  'use strict';

  angular.module('app.features', [
    'app.login',
    'app.home',
    'app.operations',
    'app.management',
    'app.customers'
  ]);
})();

(function() {
  'use strict';

  angular.module('app.customers', [
    'app.layout'
  ]);
})();


(function() {
  'use strict';

  angular
      .module('app.customers')
      .controller('CustomersListController', Controller);

  Controller.$inject = ['customerService', '$state'];

  function Controller(customerService, $state) {
    var vm = this,
      searchText;
    vm.customerService = customerService;
    vm.fetchCollection = fetchCollection;
    vm.deleteCustomer = deleteCustomer;
    vm.goToEdit = goToEdit;

    initialise();

    function initialise() {
      //some cool setup code here...

    }

    function fetchCollection(page, perPage){
      //some logic here
    }

    function deleteCustomer(model) {
      //delete logic
    }

    function goToEdit(model) {
      $state.go('customer.edit', {customerId:model.id});
    }

  }
})();

そこで、CustomersListController で定義された関数をカバーするドキュメントを書きたいと思います。

リレーションシップを定義する方法を示す受け入れられた回答でこの投稿を見たので、次のようにコードでこれを使用しようとしました:

/**
 * @namespace app
 */
angular.module('app', [
  'app.core',
  'app.features'
]);

/**
 * @class app.features
 * @memberOf app
 */
(function() {
  'use strict';

  angular.module('app.features', [
    'app.login',
    'app.home',
    'app.operations',
    'app.management',
    'app.customers'
  ]);
})();

/**
 * @class app.customers
 * @memberOf app.features
 */
(function() {
  'use strict';

  angular.module('app.customers', [
    'app.layout'
  ]);
})();

/**
 * @class app.customers.CustomersListController
 */
(function() {
  'use strict';

  angular
      .module('app.customers')
      .controller('CustomersListController', Controller);

  Controller.$inject = ['customerService', '$state'];

  function Controller(customerService, $state) {
    var vm = this,
      searchText;
    vm.customerService = customerService;
    vm.fetchCollection = fetchCollection;
    vm.deleteCustomer = deleteCustomer;
    vm.goToEdit = goToEdit;

    initialise();

    function initialise() {
      //some cool setup code here...

    }
        /**
     * @name fetchCollection
     * @function
     * @param {Number} page
     * @param {Number} perPage
     * @memberOf app.customers.CustomersListController
     * @description This is the Customers List controller
     * @returns {Array} An array of customer records
     */
    function fetchCollection(page, perPage){
      //some logic here
    }

    function deleteCustomer(model) {
      //delete logic
    }

    function goToEdit(model) {
      $state.go('customer.edit', {customerId:model.id});
    }

  }
})();

私はgulp-documentationを使用しており、次のようにタスクを設定しています。

gulp.task('build_docs', [], function () {
  var documentation = require('gulp-documentation');
  gulp.src(paths.angularAppFiles)
    .pipe(documentation({ format: 'html' }))
    .pipe(gulp.dest('./docs-html'))
});

実行すると、次の出力が生成されます

ここに画像の説明を入力

左側のナビゲーションに正しい階層を表示するという点で、より読みやすいものを望んでいたため、app.features が 2 番目のレベルに、app.customers が 3 番目のディレクトリ スタイルに表示されます。

また、「モジュール」も出力にリストされていることに気付きましたが、それがどのように生成されたのかわかりません。上記で共有したコードのモジュールの 1 つにモジュール宣言とコントローラー宣言がありますが、JSDoc はどこからこれを取得するのでしょうか?

JSDoc 構文を使用して、Angular アプリケーションで宣言されたモジュールとそれに関連するクラス (コントローラー、サービス、ディレクティブなど) の間の関係を定義し、生成された出力で簡単にナビゲーションできるようにネストされたビューに表示する正しい方法は何ですか?

編集

ngdocs とgulp-ngdocsプラグインにも出くわしましたが、まだ多くの問題が未解決で、あまり活発なレポではないようです。このプラグインとその適合性についてコメントを提供できますか? サンプルのgrunt-docsバージョンをダウンロードして実行しましたが、これは十分に機能しているように見えますが、親の 'rfx' モジュールをクリックしてもページの読み込みに失敗します (ブラウザー コンソールに 404 が表示されます) - 正直に言うと、少し緊張します!

4

1 に答える 1