Document generator with AngularJS Application

みなさんはAngularJSアプリケーションを作るさいに、ドキュメントの生成をしていますか？

AngularJSではngdocという形式のドックコメントでドキュメントを生成できるDgeniを使っています。では、AngularJSで作ったアプリケーションはどうするかと言うといくつかの選択肢があります。

JavaScript document generator

JSDoc
YUIDoc
- angular-doc （リポジトリは消えてる）\
Doxx
Docco

まず、選択肢の一つとしてJavaScript用のドキュメント生成器を使うことができます。この場合のメリットは従来通りのドックコメントを書けば良いため学習コストを低く保つことができます。しかし、AngularJS独自の区分（provider、directive…）でクラスを区分けしようとすると、空のネームスペースを作ったり、コードに沿わないドックコメントを書く必要が出てきたりします。そこに対して解決策があるならAngularJSアプリケーションで使うという選択肢を取ることができます。

/**
 * @namespace module
 */

/**
 * @namespace module.services
 */

/**
 * require service factory 
 *
 * @name Require
 * @function
 * @memberOf module.services
 * @param {ng.$http} $http {@link https://docs.angularjs.org/api/ng/service/$http}
 * @param {Content} content Content loader
 * @param {String} [PROXY_API_URL] Proxy URL
 * @return {Function} require function
 */
function Require($http, content, PROXY_API_URL) {
  /**
   * load script
   *
   * @function
   * @memberOf module.services
   * @param {String} source script file URL
   * @param {Function} callback callback that is called when load the script
   */
  return function require(source, callback) {
    // …
  };
}

module.service('require', ['$http', 'content', 'PROXY_API_URL', Require]);

Instant document generator

ExplainJS

変わり種として左右にドックコメントとコードを表示する簡易的なドキュメント生成器を扱う選択肢もあります。ドックコメントをそのまま表示するだけなので、どのような方式のドックコメントにも対応できることがメリットです。

AngularJS API Doc clone generator

※注名前は似てますが全て別物です

ngdoc形式でドックコメントを書きたい場合はAngularJS API Docクローンのドキュメント生成器が選択肢に入ります。すぐにngdoc形式のドックコメントからドキュメントを生成することができるのがメリットですが、あくまでもクローンなのでツールによってngdocのサポート範囲が異なるところに注意が必要です。（providerが指定できないなどAngularJSで使われているドックコメントがそのまま使えないことがある）

/**
 * @ngdoc directive
 * @name ev.directive:evWheel
 *
 * @description
 * The `evWheel` directive allows you to specify custom behavior on mousewheel event.
 *
 * @element ANY
 * @param {expression} evWheel {@link http://docs.angularjs.org/guide/expression Expression} to evaluate upon
 * mousewheel. (Event object is available as `$event`)
 *
 * @example
 * &lt;div ev-wheel="sameCallback()"&gt;...&lt;/div&gt;
 */
function evWheel($parse) {
  return function(scope, element, attr) {
    …
}

余談ですが、ngdocではcontrollerという区分はサポートされていません。そのため、AngularJSアプリケーションで使う場合はcontrollerをサポートしている拡張されたジェネレーターを使う必要があります。（廃止予定のcontrollerは使わないのが正しいですが）

ngdoc supported generator

Dgeni

完全にngdoc形式をサポートしているのはDgeniのみになります。そのためAngularJSと同様のドックコメントを書けるというのがメリットですが、HTMLなどを生成するために必要なテンプレートを自分で作成する手間がかかります。また、カスタマイズできる領域が他のドキュメント生成器よりも広く、ドックコメントの構文から生成するドキュメントまで自由に変更できますが、その分覚えることが多く、導入までの敷居が高くなっています。

/**
 * @ngdoc service
 * @name require
 * @module module
 * @kind function
 * @requires $http
 * @requires $content
 * @requires PROXY_API_URL
 * @description
 * 外部ファイルのコードを読み込む。
 */
function Require($http, content, PROXY_API_URL) {
  return function require(source, callback) {
    // …
  };
}

※テンプレートにdgeni-markdownを使用しています

What to choose

どれを使うべきかは、ユースケースによって変わってきます。例えば開発者がコードを読むときの助けにするためにドキュメントを生成する、公開用のAPI Docを作成するために生成する、とりあえずドックコメントの検証をする・・・などで求めるドキュメント生成器が変わります。

これは個人的な見解になりますが、ある程度どのユースケースでも対応できるものをあげると、ngdocを使わないならJSDocを。ngdocを使うならDgeniを採用するのをお勧めします。 JSDocは定番だけあって情報量が多く、テンプレートのカスタマイズまで可能なため、開発者向けのドキュメントから、公開用のAPI Docまで幅広く扱うことができます。 Dgeniは導入するまでが大変ですが、一度導入さえしてしまえば完全なngdoc形式が扱えるため、AngularJSと同じようにドックコメントを書けない・・・という事故をなくせるため安心してコメントを書くことができます。

また、JS界隈の流れは速いので他にもAngularJSアプリケーションで使えるドキュメント生成器はあると思います。こんなものを使っているよ！というのがあればぜひ教えてください。

蛇足。

Angular2だとどうなるんでしょうね。 DgeniにTypeScript packageが追加される気はしてますが、バッサリ捨てにかかりそうな気もしてます。 AngularJSアプリケーションを作る選択肢としてbabelという方向性も捨て難いので、ES6やTypeScriptに対応したドキュメント生成器なんかも漁ってみないとダメですね。