Handle private named parameters in generated docs.

[munificent]

Private named parameters affect Dartdoc in two places:

• When generating docs with a comment reference that refers to a private named parameter, use the corresponding public name.

• When generating a signature for a constructor with a private named parameter, use the corresponding public name for the parameter in the signature.

So given a class like:

class C {
  int _x;

  /// Make a new [C] with [_x].
  C({required this._x});
}

Then the Dartdoc looks like:

Make a new C with x.

C({required int x});

Fix #4114.

[munificent]

Sorry for the redundancy with @lrhn's PR. I forgot that he did that a while back. :)

[szakarias]

If possible, I would like us to get rid of the string manipulation and just get the public name directly from the analyzer. Given the docs on FieldFormalParameterElement the name property should give us the public name. (If it doesn't I think it's a bug in the analyzer)

[munificent]

If possible, I would like us to get rid of the string manipulation and just get the public name directly from the analyzer.

Good point.

Given the docs on FieldFormalParameterElement the name property should give us the public name.

Oh, you're right it should. The fact that this is working is actually wrong. The name for a FieldFormalParameterElement declared with a private should be the public name only if the field formal is a valid private named parameter. For that to be true, the parameter needs to be in a library on the latest language version and when the "private-named-parameters" experiment is enabled. Neither of those is currently true for the dartdoc tests.

So the reason this test passed is because the this._x parameter was not a valid private named parameter, and thus name used the original private name, and thus hasPrivateName returns true. If the library was correctly using private named parameters, then the name would be x, and we wouldn't get into here at all. So this code does the wrong thing when private parameters are disabled and when they are enabled. Oops!

To fix this, I need to update the code here, but also:

1. Change the dartdoc tests to enable the experiment and use the latest language version for the code being analyzed.
2. Get a new version of analyzer published that exposes the privateName getter we need to tell whether a field formal is a valid private named parameter or not.
3. Update dartdoc to use that new analyzer version.

I'll start a thread with analyzer folks about 2 and then update this PR.

[lrhn]

I'd want to land this anyway, because it works on positional parameters too.

I'll bet the analyzer name-fiddling only provides the public name for named parameters, and then I'll have to do:

 Foo(int banana) : _banana = banana;

for all eternity anyway.

[lrhn]

Sorry for the redundancy with @lrhn's PR.

NP, this looks cleaner.

(BTW, should we consider moving the dart-doc and dart_style repos into the SDK repo, since they are so tightly coupled to the analyzer code base? Even removing experiment flags has extra steps when you have to wait for the SDK to be released first.)

[munificent]

(BTW, should we consider moving the dart-doc and dart_style repos into the SDK repo, since they are so tightly coupled to the analyzer code base? Even removing experiment flags has extra steps when you have to wait for the SDK to be released first.)

I've certainly thought about this for dart_style. But I do like that:

• I can use the normal GitHub PR UI for contributions to dart_style.
• It has it's own little issue tracker dedicated to formatter issues.

[munificent]

because it works on positional parameters too.

The current state of this PR might work for positional parameters, but it's also broken. The correct fix is to use the new privateName API in the element model. That will tell you if a formal parameter is a private named parameter and, if so, what the original private name is. (The name field on the element will tell you the corresponding public name.)

But that only works for private named parameters. For private positional parameters, the privateName will always be null and name will be the original private name. I admit the API is a little confusing here, but it seemed to cause the least refactoring in the rest of the many many places in analyzer/analysis_server that were already using name.

If we want dartdoc to remove the _ from private positional parameters in API docs (which I would like too), we'll have to handle those specially.

[munificent]

Looks great, thank you!