Should a comment reference on a type alias be able to refer to members of the aliased type?

[srawlins]

Today we place a declaration's members into the resolvable scope of the declaration's doc comment, including inherited ones:

class C {
  int foo = 1;
}

/// Refer to [foo].
abstract class D implements C {}

That comment reference resolves to C.foo.

But we don't do anything similar for type aliases. For example, should the reference here resolve to int.isEven?

/// Can I refer to [isEven]?
typedef T = int;

There are several attempts to reference like this in the Dart SDK, e.g. on SetMixin (the comments resolve in dartdoc because it has a separate resolution mechanism).

[srawlins]

I think we should support referencing the members of the aliased type. It seems sensible, given someone wants to document a type alias.

[lrhn]

I'd say "no". The rule I use to understand what's in scope is that it's what's in scope inside the commented declaration (where "in scope" really means "can be referenced by a raw identifier" rather than the actual lexical scope). The members of the aliased type is not in scope "inside" the type alias.

That said, aliases that allow static member access could be considered "special", and provide access to at least those static members. Could say that they give access to the instance members too, for good measure. But it's because they're special, not because it's obvious.

[srawlins]

As a concrete example, if we wanted to keep a doc comment on SetMixin and refer to members of SetBase (the aliased type), like add and length, should they just be written as [SetBase.add] and [SetBase.length]? (They would appear at api.dart.dev with that qualified name, 'SetBase.add' and 'SetBase.length'.)

[eernstg]

The language specification unambiguously defines the current scope for a documentation comment:

Documentation comments are comments that begin with the tokens /// or /**. Documentation comments are intended to be processed by a tool that produces human readable documentation. The current scope for a documentation comment immediately preceding the declaration of a class C is the body scope of C. The current scope for a documentation comment immediately preceding the declaration of a non-redirecting generative constructor k with initializing formals is the formal parameter initializer scope of k. Otherwise, the current scope for a documentation comment immediately preceding the declaration of a function f is the formal parameter scope of f.

This basically implies that a documentation comment on a class can "see" the members declared in the body of that class, the formal type parameters of the class, if any, and anything in the enclosing library scope (including imported stuff).

We should probably make this specification slightly more detailed and say that it is possible to refer to an identifier id in this documentation comment if it can be resolved using lexical lookup (as defined in the section 'Lexical Lookup'), such that we have access to members of the interface of the class that are inherited from the superclass or "promised" by the implements clause, not just the members that are declared in the class itself.

However, it is not obvious to me that the relevant references in the documentation of a declaration are exactly the ones that are the result of resolving an identifier in the body of said declaration, even with that clarification about this.id.

You could also say that the members of the interface of a type are relevant to the documentation of a declaration that introduces said type into the enclosing scope. Some declarations introducing a type will also have formal type parameters, and they'd be relevant as well.

I think this means "no change" to the current behavior, except that members of a type which is aliased in a typedef should be available as well. (But there could be additional type-introducing declarations in the future).

An obvious corner case to consider would be typedef F<X extends Widget> = X; which would consider the members of F to be the members of Widget, ignoring the fact that F<MySpecialWidget> has a different set of members (some members in addition to the ones that Widget has, and some members shared by both, but with different signatures).

I think it would make sense to generalize the rules about documentation comments along these lines. Presumably, it would be a non-breaking change.