Dartdoc does not narrow parameter types in descendants

[anders-sandholm]

From @alsemenov on October 6, 2017 2:47

Lets consider class dart:io:Socket as an example. Its description reads:

abstract class Socket
Implements Stream<List<int>>, IOSink

Lets look at the methods and properties of the class Socket
On the front page:

first → Future<List<int>>
Returns the first element of the stream.
read-only, inherited

Following the link:

Future<T> first
Returns the first element of the stream.

Stops listening to the stream after the first element has been received.

Please, note that <List<int>> is now replaced by T, which is confusing.
The same situation is observed for property last.

For methods situation is a bit different. On the front page:

distinct([bool equals(T previous, T next) ]) → Stream<List<int>>
Skips data events if they are equal to the previous data event.
inherited

Following the link:

Stream<T> distinct([bool equals(T previous, T next ) ])
Skips data events if they are equal to the previous data event.

Please, notice that parameter type T is replaced wih actual type sometimes.

pipe(StreamConsumer<List<int>> streamConsumer) → Future
Pipe the events of this stream into streamConsumer.
inherited

Copied from original issue: dart-lang/sdk#31020

[anders-sandholm]

@alsemenov, thanks for filing the issue.
Dartdoc has it's own issue tracker at https://github.com/dart-lang/dartdoc/issues.
I'll move the issue over there.

[jcollins-g]

The first example is working as (currently) intended. Dartdoc canonicalization eliminated the creation of duplicate entries for inherited members of classes. Instead, when clicking on the entry, you will get the original definition(*) for the member. This is indicated by the navigation change as well.

For the second example, I don't see a distinction; both examples are inherited. From the perspective of the inheriting class, you see the parameterized types, but from the parent class, you do not.

The current situation is a tradeoff, between making it easy to discern where a member is inherited from vs easy to determine what its type parameters are. So far, the bulk of feedback has been strongly biased toward the former.

A possible way to resolve this tradeoff to solve both needs is to create pages for the inheriting class's context that somehow make it extra clear where the inherited object comes from while still displaying the inheriting class's type resolution. @alsemenov, if you think that would be helpful, I can mark this as a possible enhancement. It'll of course be prioritized based on feedback coming in. Thanks again for the report!

(*) - from the perspective of the public interface of the package. Depending on reexports and private libraries, the code may actually have the original definition elsewhere.

[alsemenov]

Regarding the first example, is it possible to parametrize the pages of base class, so pages of descendat classes could refer to it as page.html?T=TypeName. For example, https://api.dartlang.org/stable/1.24.2/dart-async/Stream/first.html?T=List <int> So when page is opened with parameters T=List<int> T is substituted by List<int>. Probably such substitution of T can be performed in browser without server interaction. This way you still keep a single copy of each member description, and more correct descriptions for members of descendant classes.

Regarding the second example, I think it is a bug. The description:

distinct([bool equals(T previous, T next) ]) → Stream<List<int>>
Skips data events if they are equal to the previous data event.
inherited

is found on the dart:io:Socket page, which states that T from Stream<T> is List<int> now. So class Socket is not parametrized by T now. However T is still used in the description of the method distinct on the same page. This is very confusing, because T is not defined on this page and because in the same method description T is replaced by List<int> in the return type definition.

[jcollins-g]

For the first example, that might be one way to solve the problem. The parameterization would also have to include sufficient navigation information to indicate that these type parameters are specific to the original context. Problems with dartdoc keeping track of this sort of thing lead to our second example:

What you're talking about from the second example is another working as intended bit, even though it is confusing. <T> from dart:io:Socket means something different than it does from Stream's context. List<int> is passed to Stream to create the return type. T in dart:io:Socket, is class Socket's parameter, not class Stream's.

In fact, recent changes to type handling have actually broken this in the head version of dartdoc, I'm going to file a separate bug.