Dart 註解

Dart 註解

Dart 語言總共支援三種註解：單行註解、多行註解、文件註解；編譯器會忽略註解內一般文字，只有文件註解可用來產生程式文件。

撰寫註解的目的，是方便開發人員閱讀程式，了解程式的功能與用途；同時也能透過註解暫時遮蔽某段程式，用於偵錯、測試與問題排查。

文件註解可搭配工具自動產生程式輔助文件，除了方便自己查閱程式功能，也能讓其他開發者快速看懂你開發的程式。

如果有接觸過其他程式語言，能快速上手註解寫法，語法概念與 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. 核心語法規則

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] 飼料
  ///
  /// 一隻羊駝每週通常消耗一捆乾草。
  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 資料夾，打開後可查看自動產生的API文件

配套工具

1. 文件產生工具：dart doc 用途：解析 Dart 原始碼，自動產生 HTML 格式專案 API 文件；Dart 官方API文件即使用此工具建置。
2. 註解撰寫規範參考：官方指南《Effective Dart: Documentation》，可查閱標準的註解結構與書寫風格。

重點整理

註解類型對照表

註解類型	開頭符號	跨行能力	支援巢狀	使用時機
單行註解	//	不支援，僅限單行	無	單行備註、程式待辦事項
一般多行註解	/* */	支援任意多行	支援巢狀	遮蔽大段程式、長篇說明文字
文件註解	/// / /** */	支援多行	不建議巢狀	為類別/方法/變數撰寫API說明，自動產生官方文件，支援[]連結識別名