Uint8List inherits from TypedData but docs don't show it

[Hixie]

Uint8List: https://master-docs-flutter-io.firebaseapp.com/flutter/dart-typed_data/Uint8List-class.html
...has a buffer property, which links to TypedData's buffer: https://master-docs-flutter-io.firebaseapp.com/flutter/dart-typed_data/TypedData/buffer.html
...which implies that Uint8List is related to TypedData, but this fact appears neither on the docs for Uint8List nor those from TypedData: https://master-docs-flutter-io.firebaseapp.com/flutter/dart-typed_data/TypedData-class.html

[jcollins-g]

Uint8List implements an abstract private class, _TypedIntList, which extends TypedData. The intermediate private class is the part that makes this tricky.

This is a behavioral inconsistency to dartdoc's answer to this question: If a public class implements/extends a private class, should that private class's public superclasses/mixins/interfaces be documented as if the original class extended/mixed in/implemented them?

Dartdoc's current answer to this is no -- a private class hides any types that it inherits from and therefore we don't advertise the type on the page. From that logic, it's a bug in canonicalization that we don't consider buffer to be owned by this class; we should be pretending that Uint8List implements that or at least owns the implementation of it.

But if the answer should be "yes", then the bug is that Uint8List doesn't show these types somehow, presumably as "Implements", and only pretend members declared in _TypedIntList are owned by Uint8List.

I can see a good argument for either case. Given no other data, however, I'll move toward maintaining dartdoc's current "no" to this question and correct the bug as listed first, above.

[Hixie]

i think "no" is the only consistent answer. suppose you had
C <- _B <- A
D <- A
... where A is the base class and _B introduces a public member. If you document it in A, then it'll be confusing for people looking at A from the perspective of using D (or indeed, from the perspective of using A directly).

[Hixie]

oh nevermind, i misunderstood.

Now that I understand what you mean, I think the answer should be yes, because otherwise it's omitting real information about the class hierarchy.

Suppose C <- _B <- A, people will pass on Cs where As are expected. If I look at the docs and don't see A mentioned, I'll be confused.

[jcollins-g]

The argument against goes: If I want C to be of type A, I'll say C <- A via implements, rather than relying on it indirectly through the private class.

However, come to think of it, the language has already answered this question: it says yes, A is part of the type information for C regardless of public/private distinction. Dartdoc should be documenting that reality.

[gspencergoog]

If the hierarchy is:

class A {
  /// Prints an 'a'.
  void a() {
    print('a');
  }
}

class _B extends A {
  /// Prints a 'b'.
  void b() {
    a();
    print('b');
  }
}

class C extends _B {
 /// Prints a 'c'.
  void c() {
    b();
    print('c');
  }
}

What should Dartdoc do about documenting the public function b? It's defined in a hidden class, but available to C, and part of the public interface of C. Does it just document b as if it were implemented in C? That's the "yes" answer from above, right?

[jcollins-g]

Correct. Dartdoc should document b() as if it was implemented in C. Currently, it almost does this right, except I believe it will claim b() is "inherited" in C (even though what it is inherited from is not clear, because the inheritance should just say C <- A).

While my memory is a little fuzzy, I think the original bug is that the private type _B may also hide that a() came from A, so C will claim to have inherited a() from somewhere but it won't be clear where from.

[lrhn]

I just had someone stumble over this and think that Uint8List did not implement TypedData.

I think the answer should be "yes". The reason for DartDoc to list interfaces implemented by a class is that it is useful information. Not listing transitively implemented types is reasonable because they are implied by the listed types.
So, in the case where a transitively implemented type is not represented by another listed type, omitting it is misleading. The documentation should represent the type hierarchy, not the textual declaration, because the latter isn't useful to the reader.

(Technically, if some class had implements Iterable<int>, List<int>, it would probably be fine to omit Iterable<int> since it is implied by List<int> anyway, and you can follow it by clicking the transitive implemented type links).

(And for the record: I wrote the classes knowing that TypedData would be inherited through _TypedIntList, and was surprised to see it not reflected in DartDoc.)

[natebosch]

Do we have an idea of when this fix will be live on api.dart.dev? Are we tracking that anywhere, or is there a more appropriate place for me to file an issue to track? Recent dev SDK docs are not showing these implemented types.

Another place I notices is that Queue doesn't show it implements Iterable because of the not-exposed EfficientLengthIterable class, but shows all the iterable methods as inherited.

[jcollins-g]

It looks like either a new variant of this problem has appeared, or the problem was not completely fixed by #2354.