Dart 注釋

注釋

在說明成員以及類型的時候應(yīng)該使用 doc 注釋。

盡管 Dart 支持兩種類型的 doc 注釋（/// 以及 /**），我們推薦 ///，因為它更加緊湊（/** 以及 */ 用于多行注釋，并且有兩行是空的）。在有些情況下，/// 也更加容易閱讀，比如在某個 doc 注釋中包含了一個列表，并且該列表使用 * 來標記各個列表項。

// good
/// Parses a set of option strings.
///
/// For each option:
///
/// * If it is `null`, then it is ignored.
/// * If it is a string, then [validate] is called on it.
/// * If it is any other type, it is *not* validated.
void parse(List options) {
  // ...
}

在 doc 注釋中，你可以使用 markdown 格式。

應(yīng)該使用單行注釋。

// good
greet(name) {
  // Assume we have a valid name.
  print('Hi, $name!');
}

// bad
greet(name) {
  /* Assume we have a valid name. */
  print('Hi, $name!');
}

你可以使用塊注釋（/* ... */）來在某段代碼之外進行注釋。

注釋也應(yīng)該像普通句子一樣大小寫并且添加標點。

這并不是說注釋就應(yīng)該是一個完整的句子，盡管多數(shù)情況下它應(yīng)該是一個完整的句子?！胺祷貤l目的數(shù)量”就是一個可接受的注釋。

// good
// Remove the last item from the collection.

// bad
// remove the last item from the collection

在注釋中應(yīng)該使用方括號把相應(yīng)域中的標識符標記出來。

如果你把變量、方法或者類型的名稱放在方括號內(nèi)，那么文檔生成器就可以查找到相應(yīng)的名稱，并且將其與代碼連接起來。

// good
import 'dart:math';

/// Rolls both [Dice] and returns the highest rolled value.
num greatestRoll(Dice a, Dice b) => max(a.roll(), b.roll());

//

在文檔注釋中應(yīng)該描述函數(shù)簽名。

在其他語言中，要使用很多的標簽以及各個部分來說明函數(shù)的參數(shù)是什么，返回值又是什么。

//bad
/// Defines a flag with the given name and abbreviation.
///
/// @param name The name of the flag.
/// @param abbr The abbreviation for the flag.
/// @returns The new flag.
/// @throws IllegalArgumentException If there is already an option with
///     the given name or abbreviation.
Flag addFlag(String name, String abbr) {
  // ...
}

使用 Dart 則相當便捷，你可以直接使用方括號把參數(shù)等信息整合到函數(shù)描述中。

// good
/// Defines a flag.
///
/// Throws an [IllegalArgumentException] if there is already an option named
/// [name] or there is already an option using abbreviation [abbr]. Returns
/// the new flag.
Flag addFlag(String name, String abbr) {
  // ...
}

注釋應(yīng)該放在元數(shù)據(jù)注解之前。

// good
/// _Deprecated: Use [newMethod] instead._
@deprecated
oldMethod();

// bad
@deprecated
/// _Deprecated: Use [newMethod] instead._
oldMethod();