Parameters shadow properties in dartdocs (lots of broken links in Flutter docs as a result)

[Hixie]

The Opacity constructor looks like this:

  /// Creates a widget that makes its child partially transparent.                                                                                                                                                                                                  
  ///                                                                                                                                                                                                                                                               
  /// The [opacity] argument must not be null and must be between 0.0 and 1.0                                                                                                                                                                                       
  /// (inclusive).                                                                                                                                                                                                                                                  
  const Opacity({                                                                                                                                                                                                                                                   
    Key key,                                                                                                                                                                                                                                                        
    @required this.opacity,                                                                                                                                                                                                                                         
    Widget child,                                                                                                                                                                                                                                                   
  }) : assert(opacity != null && opacity >= 0.0 && opacity <= 1.0),                                                                                                                                                                                                 
       super(key: key, child: child);

   /// ...
   final double opacity;                                                                                                                                                                                                                                             

Our goal in writing this was that the constructor docs would link to the opacity field's page. Instead, it doesn't link anywhere.

It would be much nicer if arguments were not considered "in scope" for [...] links, since they don't actually have their own page to link to, so it doesn't really do any good to link to them.

Technically in the Flutter docs this manifests as "Broken links, widespread", but I guess it's really a mistake on our part (we didn't understand that arguments would be considered "in scope" and would thus prevent the links from working) so it's also "Enhancements considered important but without significant data indicating they are a big win" and I've marked it P2.

[jcollins-g]

The scoping change to arguments is fairly recent (around the time of canonicalization) in order to reduce warnings, as I recall there were many places which had arguments referenced in square brackets. We could alter the scoping rules to only consider arguments if other possibilities fail, reducing their priority in the lookup order.

[Hixie]

Sounds reasonable. For Flutter we have the convention that square brackets shouldn't be used for arguments at all, though I understand this isn't the case for other projects so it may be impractical to implement that uniformly.

[yjbanov]

Today, when there's is a name conflict between a field and a parameter. There is a way to resolve it:

class Foo {
  int foo;

  /// [foo] points to the parameter.
  /// [Foo.foo] points to the field.
  void bar(int foo) {}
}

If we change scoping rules, we should also update the way such conflicts are resolved.

[Hixie]

I would just remove the [...]-linking to arguments entirely. I think if we want to have a way to link to arguments we should have a separate syntax for them.

I would strongly discourage using [Foo.foo] to refer to a property from a method on that class because it makes it look like a constructor (or maybe a static... or maybe suggests Foo is another class...). Certainly it would be weird because it would look so different from [bar] in the same context, despite being identical. It also reads terribly.

[jcollins-g]

Since there's nothing to link to for an argument, providing a way to resolve the conflict so you don't link to something seems like a lower priority to me? After all, if you don't want a link, you'd just not put one there...

Removing the [...]-linking is doable. However as you pointed out earlier, there's not anything to link arguments to anyway. So reducing the priority would have the same impact on the output -- the only difference will be in how this is warned. Reducing the priority will choose to link to a field, etc, when a conflict is detected yet not warn when an argument link is attempted. Removing it entirely will add warnings.

I think what I'm leaning toward is to make the warning system more granular so we can enable and disable specific warnings and implement this by reducing the priority in the parser.

[yjbanov]

@jcollins-g What would the warning system produce in the example above?

[Hixie]

Yeah I'm totally fine with [foo] linking to the argument if there's nothing else it could plausibly link to. Yegor on a thread internally has been arguing that he wants a way to unambiguously link to arguments even if the arguments clash with a property name, hence my suggestion for a separate syntax. But that's not a high priority for me personally.

[jcollins-g]

Expanded the example slightly for clarity.

For completeness, current behavior:

class Foo {
  int foo;

  /// [foo] points to the parameter.             <<< No warning, doesn't link and is recognized internally as a parameter
  /// [baz] points to the parameter.             <<< No warning, doesn't link and is recognized internally as a parameter
  /// [Foo.foo] points to the field.             <<< No warning, links to field
  void bar(int foo, int baz) {}
}

If support for argument linking is removed entirely:

class Foo {
  int foo;

  /// [foo] points to the parameter.           <<< No warning, links to field
  /// [baz] points to the parameter.           <<< warning: can not link [baz]
  /// [Foo.foo] points to the field.           <<< No warning, links to field
  void bar(int foo, int baz) {}
}

If argument linking is deprioritized:

class Foo {
  int foo;

  /// [foo] points to the parameter.             <<< No warning, links to field
  /// [baz] points to the parameter.             <<< No warning, doesn't link and is recognized internally as a parameter
  /// [Foo.foo] points to the field.             <<< No warning, links to field
  void bar(int foo, int baz) {}
}

[Hixie]

FWIW, either of the latter two sounds good to me.

[yjbanov]

Neither of the options offer conflict resolution, which is a regression from the status quo. However, if #1259 is fixed first, then this would not be an issue.

[jcollins-g]

#1259 will require sdk #27570 first, so that's not likely to happen quickly.

Ideally dartdoc and analyzer would have the same idea about what's going on here, with dartdoc inheriting knowledge about that from the analyzer. If there's not a clearly awesome choice here, it might be better to put off trying to hack this up in dartdoc.

[yjbanov]

#1259 will require sdk #27570 first

If I understand correctly, the two issues are unrelated. dart-lang/sdk#27570 is about allowing putting @required on a field rather than a parameter, and #1259 is about putting dartdocs on parameters.

However, now that I think of #1259, I don't think it would completely eliminate the issue. Sometimes you want to refer to multiple parameters in one sentence. #1259 is only about documenting one parameter at a time. Of course, the chance of name conflict is smaller in this situation, it does remove the reliability of the feature. I want to be able to trust dartdoc links 100%, just like I trust Dart's lexical scoping rules.

Example:

/// Adds [a] and [b], and divides the result by `2.0`.
average(double a, double b) => (a + b) / 2.0;

Even with #1259 fixed, I'd still want to be able to refer from the dartdoc of one parameter to another parameter.

Example:

/// Computes the average of two numbers.
average(
  /// Added to [b].
  double a,
  /// Added to [a].
  double b,
) => (a + b) / 2.0;

[yjbanov]

Ideally dartdoc and analyzer would have the same idea about what's going on here

+1000. I'd love to see dartdocs become part of the language and understood by all static analysis tools (code search, navigation, language-aware code highlighting, refactoring, formatting, etc, etc)