內容

Dart 支援單行註解、多行註解和文件註解。

單行註解

#

單行註解以 // 開頭。// 和行尾之間的所有內容都會被 Dart 編譯器忽略。

dart
void main() {
  // TODO: refactor into an AbstractLlamaGreetingFactory?
  print('Welcome to my Llama farm!');
}

多行註解

#

多行註解以 /* 開頭,以 */ 結尾。/**/ 之間的所有內容都會被 Dart 編譯器忽略(除非註解是文件註解;請參閱下一節)。多行註解可以巢狀。

dart
void main() {
  /*
   * This is a lot of work. Consider raising chickens.

  Llama larry = Llama();
  larry.feed();
  larry.exercise();
  larry.clean();
   */
}

文件註解

#

文件註解是多行或單行註解,以 ////** 開頭。在連續行上使用 /// 的效果與多行文件註解相同。

在文件註解內,分析器會忽略所有未括在方括號中的文字。使用方括號,您可以參照類別、方法、欄位、頂層變數、函式和參數。方括號中的名稱會在文件化程式元素的詞法範圍內解析。

以下是包含對其他類別和參數的參考的文件範例

dart
/// A domesticated South American camelid (Lama glama).
///
/// Andean cultures have used llamas as meat and pack
/// animals since pre-Hispanic times.
///
/// Just like any other animal, llamas need to eat,
/// so don't forget to [feed] them some [Food].
class Llama {
  String? name;

  /// Feeds your llama [food].
  ///
  /// The typical llama eats one bale of hay per week.
  void feed(Food food) {
    // ...
  }

  /// Exercises your llama with an [activity] for
  /// [timeLimit] minutes.
  void exercise(Activity activity, int timeLimit) {
    // ...
  }
}

在類別產生的文件當中,[feed] 會變成連結到 feed 方法的文件,而 [Food] 會變成連結到 Food 類別的文件。

若要剖析 Dart 程式碼並產生 HTML 文件,可以使用 Dart 的文件產生工具 dart doc。有關產生的文件範例,請參閱 Dart API 文件。有關如何建構註解的建議,請參閱 有效 Dart:文件