如何为 Dart 函数参数添加 Doc 注释？

Question

我们可以轻松地为 Dart 类变量添加 Doc 注释，例如

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

}

我怎样才能对 Dart 函数参数做同样的事情，例如我试过这个

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

}

但它没有显示任何东西。如果不可能，请建议我任何替代方案。

Answer 1

您应该像这样使用文档注释：

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

Answer 2

使用这样的直接语法来记录函数的参数是违反 Effective 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]) ...