How to put Doc comments for Dart function parameters?

Question

We can easily put Doc comments for Dart Class variables e.g.

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

}

How can I do the same for Dart Function parameters e.g. I tried this

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

}

But it's not showing anything. If it's not possible please suggest me any alternative.

Answer 1

It is against the Effective Dart conventions to document parameters of functions using a direct syntax like that. Instead, use prose to describe the parameter and how it relates to the function's purpose.

// 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" }) ...

Here's perhaps a more practical example:

/// 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

You should use the doc comment like this:

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