Better constructor/function parameter documentation

[Pante]

From my understanding, there are two main ways in which API users browse documentation:

• Viewing the generated Dart docs, such as the one on api.flutter.dev.
• Hovering over a constructor/function in the IDE to see its documentation.

Prose doesn't scale

Effective Dart recommends using prose to explain parameters, return values, and exceptions. This works well for return values and exceptions since there are typically only a few of them. However, the same isn't true for parameters. Constructors and functions can have many parameters. At the extreme end, Flutter's TextField.new has 60+ parameters while ThemeData.new has 84.

Using prose to explain such a sheer amount of parameters is neither practical nor useful.

On the API designer's side, it is hard to write and maintain, the language does not warn about undocumented parameters. It is exceedingly easy to miss a parameter when writing documentation, especially when retroactively adding a new parameter.

On the API user's side, reading the documentation is akin to finding a needle in a haystack. The user has to sift through a wall of text to find the parameter they are interested in. The parameter might not even be documented at all (partially due to the above). Performing CTRL+F to search for the parameter name may be a solution when browsing the generated Dart docs, but it is not a solution when reading the documentation in an IDE.

As an exercise, try reading TextField.new and understanding what smartDashesType does.

Ultimately, given enough parameters, prose fails at answering, "What does this parameter do?"

Per-parameter documentation

To tackle this usability issue, I propose allowing individual parameters to be documented:

class Foo extends StatelessWidget {
  /// Some docs for a.
  final String a;
  final String _b;
  final String _c;
  
  /// Creates a [Foo].
  Foo({
    required this.a,
    /// Documentation for b.
    required String b,
    required String c,
    super.key,
  }): _b = b, _c = c;
}

this and super parameters should automatically inherit from their respective field's documentation. If the parameters interact in some way -—i.e., being mutually exclusive as in the case of Container.decoration and Container.color -- that interaction should then be documented at the constructor/function's level.

From a glance, it is clear to the API designer which parameters are documented and which are not. In the above example, b is documented while c is not.

Generated Dart docs

The generated Dart docs should probably include a section in the constructor/function's documentation that lists the documented parameters, simplifying look-up.

IDE

Both IntelliJ and VSCode are currently intelligent enough to show a parameter's documentation when hovering over it IF it is a this parameter.

This isn't true for super and other parameters. Their hover behavior should mimic that of this parameters.

[bwilkerson]

The proposed changes to dartdoc will require some design discussions that I'm ignoring for the moment. The proposed changes to the documentation displayed in hovers (and other contexts) however, are independent of whether or not we start supporting putting documentation on parameters. I hope to have a CL out shortly to address that request.

[bwilkerson]

The hover changes were implemented in https://dart-review.googlesource.com/c/sdk/+/434220.