[Wildcard Variables] Dartdoc Support

[kallentu]

This issue will track the work needed in Dartdoc for the wildcard variables feature.

There's probably no additional work needed for Dartdoc.
However, we should test that Dartdoc isn't broken by changes to how we represent wildcard variables in the analyzer.

[kallentu]

cc @srawlins

This issue tracks if we need anything for Dartdoc. We probably won't, but we can cross that bridge later when we have the analyzer work done :)

[bwilkerson]

If Dartdoc is still doing its own resolution of identifier references in doc comments, then a reference of the form [_] will need to be resolved differently. From dartdoc's perspective, this feature will only effect parameters, and that might be the only place that will be impacted by the change.

[srawlins]

From dartdoc's perspective, this feature will only effect parameters, and that might be the only place that will be impacted by the change.

I think also type parameters, import prefixes, and maybe record type positional fields. In particular field formal parameters and super parameters should be tested.

[srawlins]

@kallentu I closed this too soon (I had not properly enabled wildcard variables in tests). I have a question:

In dartdoc's comment resolution code, as you know, we use what analyzer gave us via it's own doc-scope resolution stuff. So now, even with the wildcard variables feature enabled, for this code:

import 'dart:async' as _;

/// Text [_].
int x = 0;

I see that [_] has been resolved to be a comment reference with a PrefixElement element.

I'm not sure how the idea of "non-binding" is implemented in the analyzer, but do you think that [_] should not resolve to that PrefixElement? It's not really a dartdoc question, as this would apply to effects in the IDE, like go-to-definition, etc.

[kallentu]

On first glance, I would assume that /// Text [_]. wouldn't refer to any element in that example. You can't access the _ prefix.

@pq How do go-to-definitions work for import prefixes? Does it link to something?

[srawlins]

Oh good point, since a prefix can be shared amongst several imports. It looks like go-to-definition currently jumps to the last import with that prefix.

Maybe rename? Which seems to work even if there are multiple imports with the same prefix.

[pq]

How do go-to-definitions work for import prefixes? Does it link to something?

If a prefix is bound, they work as you'd expect and jump you to where the prefix is declared.

For a wildcard, _ is not bound so it won't jump you anywhere

[srawlins]

Indeed, if I add this test case to pkg/analysis_server/test/analysis/get_navigation_test.dart:

  Future<void> test_x() async {
    addTestFile('''
import 'dart:async' as _;
/// Returns a [_].
String f() {
}''');
    await waitForTasksFinished();
    await _getNavigation(search: '[_', length: 1);
    expect(regions, hasLength(1));
    assertHasRegion('_]');
  }

it fails expecting one region (there are zero). Good. So then back to the question of [_] having an element or anything, if I add the following test to pkg/analyzer/test/src/dart/resolution/comment_test.dart:

  test_x() async {
    await assertNoErrorsInCode('''
// ignore: unused_import
import 'dart:async' as _;

/// [_]
void f() {}
''');

    assertResolvedNodeText(findNode.commentReference('_]'), r'''
CommentReference
  expression: SimpleIdentifier
    token: _
    staticElement: <null>
    staticType: null
''');
  }

I get a passing result. I'm thinking dartdoc just doesn't have access to the latest analyzer code that puts a null static element here. So I'll leave this ticket open until that is published.