Dart で書かれた API のドキュメントを自動生成する

ソースコードにドキュメント用コメントを付ける

次のような感じでコメントを付ける.

// lib/hello_dartdoc.dart

/**
 * A sample library to show how to use `dartdoc`.
 */
library hello_dartdoc;

/**
 * A sample class.
 */
class HelloDartdoc {

  /**
   * A constructor of `HelloDartdoc` class.
   */
  HelloDartdoc(this.variable);

  /**
   * A member variable of `HelloDartdoc` class.
   */
  String variable;

  /**
   * Returns a message with a received parameter.
   *
   * ## マークアップの仕方
   *
   * #1 リンクの記述方法
   * * [HelloDartdoc] または [これ](../hello_dartdoc/HelloDartdoc.html) は `HelloDartdoc` クラスへのリンク.
   *
   * #2 コードブロックの記述方法
   * 4 つの空白から始まる行はコードブロックとして扱われる.
   *     HelloDartdoc helloDartdoc = new HelloDartdoc('X', 'Y');
   *     String result = helloDartdoc.method('Z');
   *
   * #3 文字の装飾の仕方
   * * バッククオートで囲まれた文字列は `code font` で装飾される.
   * * アンダースコアまたはアスタリスクで囲まれた文字列は _italic_ で装飾される.
   * * 二つのアスタリスクまたはアンダースコアで囲まれた文字列は **boldface** で装飾される.
   */
  String method(String parameter) {
    return 'You called this method with $parameter';
  }
}

ドキュメントを生成する

dartdoc コマンドで上記のファイル (lib/hello_dartdoc) を処理する.

$ dartdoc lib/hello_dartdoc.dart 
Using snapshot /Users/kkohtaka/dart-sdk/bin/snapshots/utils_wrapper.dart.snapshot
Analyzing libraries...
Generating documentation...
Compiling client JavaScript...
Copying static files...
Documentation complete -- documented 1 libraries, 1 types, and 3 members.

デフォルトでは docs/ 以下にドキュメントが生成されるのでブラウザで開く.

$ ls -R docs/
0                       client-live-nav.js      external-link.png       hello_dartdoc.html      nav.json
apidoc.json             content-bg.png          favicon.ico             index.html              styles.css
body-bg.png             dart-logo-small.png     header-bg.png           interface.png
class.png               exception.png           hello_dartdoc           library.png

docs//0:
apidoc.json             hello_dartdoc.json

docs//hello_dartdoc:
HelloDartdoc.html
$ open docs/hello_dartdoc/HelloDartdoc.html

下のような HTML のドキュメントが確認できる.

Refs: https://www.dartlang.org/docs/dart-up-and-running/contents/ch04-tools-dartdoc.html

コメントの書き方

大きく, 初めのパラグラフとそれ以降のパラグラフに分けられる.

初めのパラグラフ

初めのパラグラフは一文で記述しピリオドで終わるようにする.

• 関数, メソッドのコメントの場合

三人称単数現在系の動詞で始める.

例

/**
 * Returns a message with a received parameter.
 * ...
 */
String method(String parameter) {
  return 'You called this method with $parameter';  
}

• 変数, ゲッタ, セッタの場合

名詞にする. ゲッタとセッタがある場合にはゲッタのみにコメントを書く.

例

/**
 * A member variable of `HelloDartdoc` class.
 */
String variable;

• ライブラリ, クラスの場合

名詞にする.

例

/**
 * A sample library to show how to use `dartdoc`.
 */
library hello_dartdoc;

/**
 * A sample class.
 */
class HelloDartdoc {
  ...
}

それ以降のパラグラフ

それ以降のパラグラフは自由に記述できる. ただし, 関数, メソッドの場合は用例を書くことが推奨される.
その他, 引数の説明, 副作用, 投げる可能性のある例外や外部ドキュメントへのリンクを記述すると良い.

Refs: https://www.dartlang.org/articles/doc-comment-guidelines/