Dart コメント

Dart言語にはコメントが全部で3種類サポートされています：一行コメント、複数行コメント、ドキュメントコメント。コンパイラは通常のコメント内テキストを無視します。ドキュメントコメントのみコードドキュメント生成に利用可能です。

コメントの目的は、プログラマーがコードを読み解き、機能や役割を把握しやすくすることです。また一時的にコードを無効化し、デバッグや不具合調査に活用することもできます。

ドキュメントコメントはツールを使ってコードのヘルプドキュメントを自動生成できます。自身のコード仕様確認はもちろん、他人がライブラリを利用する際の参照資料としても役立ちます。

C/C++/Java/C# などC系言語を学んだ経験があれば、すぐに理解できます。記法はほぼ共通です。

1、一行コメント //

1. // から記述開始；
2. // から行末までの内容はDartコンパイラに無視される；
3. 現在の行のみ有効、複数行にまたがる記述は不可。

サンプルコード

void main() {
  // TODO: ラマ挨拶工場クラスにリファクタリング？
  print('ラマ農場へようこそ！');
}
Code language: JavaScript (javascript)

2、複数行コメント /* */

1. 開始記号 /*、終了記号 */；
2. /* と */ に挟まれた内容はコンパイラに無視される（後述のドキュメントコメントを除く）；
3. ネスト記述に対応。

サンプルコード

void main() {
  /*
   * ラマの飼育は手間がかかる、鶏の飼育を検討してもよい

  Llama larry = Llama();
  larry.feed();
  larry.exercise();
  larry.clean();
   */
}Code language: Dart (dart)

上記コードの波括弧内コードはすべてコメントアウトされ、コンパイル対象外となりコンパイラに無視されます。

3、ドキュメントコメント

公式APIドキュメント生成用のコメントです。他の開発者がライブラリを利用する際、クラス・メソッド・引数などの仕様書として参照できます。

1. 2種類の記述形式

• 一行ドキュメントコメント：複数行に渡って /// を記述。複数行ドキュメントコメントと同じ効果。スラッシュが3本になる点に注意。
• 複数行ドキュメントコメント：/** で開始、*/ で終了。開始記号にアスタリスクが追加されている点に注意。

2. 基本文法ルール

1. ドキュメントコメント内の通常テキストはコード解析ツールに無視される；
2. 角括弧 [] で識別子を囲む特殊記法：クラス、メソッド、フィールド、トップレベル変数、関数、引数を参照可能；
3. 角括弧内の名称はコメント対象コードの字句スコープ内で解決される；
4. ドキュメント生成後、[識別子] は対応するドキュメントへのハイパーリンクに自動変換される。

サンプルコード

// 通常一行コメント：飼料クラス定義
class Food {
  String type;
  // 一行コメント：飼料の束数
  int baleCount;

  Food(this.type, this.baleCount);
}

/*
複数行通常コメント：
運動種別列挙型、ラマの運動メソッドで使用
ネストコメントのデモ
/* 内側ネストコメント */
*/
enum Activity {
  walk,
  run,
  graze
}

/// 飼育される南米ラマ科動物（ラマ、学名Lama glama）
///
/// コロンブス以前のアンデス文明では、ラマは食肉や運搬家畜として活用されていました。
///
/// 他の動物同様ラマには餌が必要です。[Food]型の飼料を与え、[feed]メソッドを呼び出してください。
class Llama {
  String? name;

  /// 指定した[food]をラマに給餌する
  ///
  /// 1頭のラマは週に干し草1束を消費するのが一般的です。
  void feed(Food food) {
    // 一行コメント：給餌ログ出力
    print("${name}は${food.baleCount}束の${food.type}を食べました");
  }

  /// ラマに[activity]の運動を[timeLimit]分間実施させる
  void exercise(Activity activity, int timeLimit) {
    print("${name}は${activity.name}を${timeLimit}分間行いました");
  }
}

void main() {
  // TODO：複数頭のラマ管理機能を後ほど拡張
  Llama larry = Llama();
  larry.name = "ラリー";

  // 干し草飼料作成
  Food hay = Food("干し草", 1);
  larry.feed(hay);

  // 20分間散歩
  larry.exercise(Activity.walk, 20);
}
Code language: PHP (php)

ドキュメント生成後：[feed] は同一クラスのfeedメソッドドキュメント、[Food] はFoodクラスのドキュメントへリンクされます。

D:\dartdemo\firstdart>dart run
Building package executable...
Built firstdart:firstdart.
ラリーは1束の干し草を食べました
ラリーはwalkを20分間行いました

D:\dartdemo\firstdart>dart doc
Documenting firstdart...
Discovering libraries...
Linking elements...
Precaching local docs for 136851 elements...
Initialized dartdoc with 50 libraries
Generating docs for library firstdart.dart from package:firstdart/firstdart.dart...
Found 0 warnings and 0 errors.
Documented 1 public library in 10.3 seconds
Success! Docs generated into d:\dartdemo\firstdart\doc\apiCode language: JavaScript (javascript)

実行後プロジェクトルートにdocフォルダが作成され、中身を開くと以下のようなドキュメントが確認できます

関連ツール

1. ドキュメント生成ツール：dart doc 役割：Dartソースコードを解析し、HTML形式のプロジェクトAPIドキュメントを自動生成。Dart公式APIドキュメントも本ツールで作成されています。
2. コメント記述ガイド：公式ガイド『Effective Dart: Documentation』。規則的なコメント構文・スタイルを確認可能です。

まとめ

一覧表

コメント種類	開始記号	複数行対応	ネスト対応	用途
一行コメント	//	不可、同一行のみ	不可	一時的な一行メモ、TODO記述
通常複数行コメント	/* */	任意複数行対応	ネスト可能	大量コード一括コメントアウト、長文説明
ドキュメントコメント	/// / /** */	複数行対応	ネスト非推奨	クラス/メソッド/変数のAPI説明、公式ドキュメント生成、[]による識別子リンク機能付き