Better documentation inference for constructor properties

[cedvdb]

I'll refer to this comment to explain the issue:

I always have to dig into the borderRadius documentation to remember what I need to put in the BoxDecoration parameters because the types are:

BoxDecoration(Color color, BoxBorder border, BorderRadiusGeometry borderRadius)

but both BoxBorder and BorderRadiusGeometry are abstract types and cannot be instantiated, so you have to dig into their documentation which incidentally is not available from the hover information in VSCode when you are hovering over BoxDecoration or it's parameters, so you have to drill down into BoxDecoration first, then find the borderRadius field (not the parameter in the constructor since it uses this.border) and then drill into the BorderRadiusGeometry type there, and then you finally find that the BorderRadius subclass is the one that you want. For newcomers this is counterintuitive, even though the name of the parameter is the same name as the class that you want. Personally I look at the type information first to understand something I don't know, and when the IDE cannot autocomplete from BorderRadiusGeometry a static method or anything I get confused.

Basically today it is not possible to add documentation to constructor properties unless those properties are members of the class Usually that means that you have to dig through a lot of documentation to find your answer which could be avoided. This is not a pressing issue but annoying nonetheless.

I've no proposal, but maybe some brain storming could lead to something. One idea is to use the doc template

/// a widget
/// 
/// {@template controller}
/// the controller bla bla bla
/// {@endTemplate}
///
/// {@template borderRadius}
///  borderRadius is bla bla bla
///  you can use one of the built in constructors: BorderRadius.circular, BorderRadius.all
/// {@endTemplate}
///
class SomeWidget {
    SomeWidget(
       StreamController controller,
       BorderRadiusGeometry borderRadius,
    )
}

When you hover the controller property, the documentation for that property is inferred from the templates available

An issue with this is that if the documentation was written in the super class it would not follow through. My hope is that the super.x feature could make those documentations tunneled.

[lrhn]

The recommended approach (or at least what the platform libraries try to do) is to have a documentation paragraph starting with

/// The [parameterName] blah blah must do blah. Otherwise whatnot blah.

If the tools could show that paragraph when hoovering over the parameter name, then it would probably be a good start.

Maybe even recognize /// The [foo] and [bar] as covering both parameters.

[leafpetersen]

Transferring this to the dartdoc repo, since as best I can tell this isn't a language issue.