如何為 Dart function 參數添加文檔注釋？

Question

我們可以輕松地為 Dart Class 變量添加文檔注釋，例如

class SomeClass {
/// Class variable Doc Comment.
var someVariable;

}

我怎樣才能對 Dart Function 參數做同樣的事情，例如我試過這個

void someFunction(
 {/// Function parameter documentation
 String funParameter="Some Default Value"}
) {

}

但它沒有顯示任何東西。 如果不可能，請建議我任何替代方案。

Answer 1

使用類似的直接語法記錄函數參數是違反有效的 Dart 約定的。 相反，使用散文來描述參數以及它與函數用途的關系。

// Instead of this

/// someFunction
/// @funParameter Does something fun
void someFunction({ String funParameter="Some Default Value" }) ...

// Or this

/// someFunction
void someFunction({
  /// Does something fun
  String funParameter="Some Default Value" 
}) ...

// Do this

/// Does something fun with the [funParameter].
void someFunction({ String funParameter="Some Default Value" }) ...

這也許是一個更實際的例子：

/// Takes the values [a] and [b] and returns their sum. Optionally a
/// third parameter [c] can be provided and it will be added to the 
/// sum as well.
int add(int a, int b, [int c = 0]) ...

Answer 2

您應該像這樣使用文檔注釋：

/// the function uses [funParameter] to do stuff
void someFunction({String funParameter = "Some Default Value"}) {
    // ..
}