Documentation on api.dartlang.org: Missing information creates ambiguity

[eernstg]

Looking at int or List, it is possible to check out parts of the supertype structure of a given class at a glance:

// On the `int` page:
Inheritance: Object > num > int

// On the `List<E>` page:
Implements: EfficientLengthIterable<E>

I just looked up Comparable<T> to check whether it's directly a subclass of Object, or there is something hiding (like EfficientLengthIterable) in between.

However, that information is not available, there is no Inheritance and Implements paragraph. I suspect that the information which is given is actually computed from the syntactic elements in the declaration (sdk/lib/core/comparable.dart declares it as abstract class Comparable<T> {..}, so there is no extends and no implements).

If you know that then it is unambiguous. But I'm just guessing what the rule is, and if you don't guess it correctly it's just information which confusingly isn't there.

So I'd suggest that we include at least Inheritance: Object > Foo. for all classes whose superclass is implicitly Object, and maybe something like Implements: (nothing). if there is no implements clause and Mixes in: (nothing). if there is no with clause.

[lrhn]

I would actually de-prioritize the superclass chain. For anything except mixins, the actual superclass of a class is an implementation detail, and the transitive superclasses are never important. The interfaces matter, but the implementation inheritance through the superclass is no more important than the one through the implements clause.

Since num is completely abstract, there is no difference between class int extends num and class int implements num, so there is no reason for the documentation to differ.

(We still have class-induced mixins, so we can't completely ignore the superclass declaration - but we'll get there!)

[kevmoo]

@eernstg – better now? https://api.dartlang.org/be/154136/dart-core/Comparable-class.html

CC @jcollins-g

[jcollins-g]

This is a question of whether we display the inheritance information even when there's nothing "useful" to say. We don't do anything different in dartdoc for this since the original request was made (other than being more accurate in what we display here thanks to bugfixes), so the original question is still valid.

I don't know what's better; decluttering for the common case of classes subclassed from Object only, or being consistent in displaying that information in placeholders.

[eernstg]

Right, there haven't been any changes with respect to the question I asked.

This is of course just an enhancement request, so nothing will break if it's ignored. ;-)

But I'll still add a few comments about why it might be useful. @lrhn says, essentially, that readers of a class documentation page do not need to know where the interface of a class C comes from, they just need to know that instances of C has a certain member (e.g., method, operator, getter, ..) with a certain signature, and they need to know the purpose and appropriate use of that member. In particular, stuff like the superclass chain is not needed.

I agree that this is typically exactly what the reader of such a page may need.

But I do think that there may be a difference between the needs of a reader of such a documentation page for a class C when the purpose is to..

• use members of an instance of C in "client code".
• investigate which type, out of several candidates, is suitable to use for a particular type annotation (say, I'm writing a method in some other class, and it has a parameter of type C ... or should it be one of the supertypes of C, maybe indirectly, or maybe this subtype I just found? ...).
• write a subtype of C, or a subclass.
• get an overview of the purpose of instances of a given class by quickly scanning over its supertypes, hoping to find some well-known ones.

In short, I'm not convinced that the "use members" point of view always reflects the actual needs of the reader, and some additional points of view may be worth keeping in mind.

But concretely, I can understand if it produces too much noise on a documentation page to include Inheritance: Object > ... even when it's only the trivial Inheritance: Object > C. On the other hand, it might be useful to have a separate hierarchy browser, with links to/from each class documentation page.

[jcollins-g]

I'm in general agreement with @eernstg on the use cases; that matches my experience. In particular, the transitive classes on a superchain are interesting when exploring new code and deciding which class to override to create a new behavior.

I think we may be able to refine this into a set of user journeys.

• A user wants a deeper understanding of how to use a particular Dart symbol. (Dartdoc's current core user journey)
• A user wants their code to take a certain type as a parameter, but doesn't know which supertype of that type may be best to use.
• A user wants to extend a class by adding or overriding methods, but isn't sure which superclass of the class they've discovered is appropriate to extend.
• A user wants to understand the importance and purpose of an instance by examining its connections to other classes via references, especially inheritance and implementation.

I can imagine a number of different possible features around these, everything from inheritance browsers to some sort of PageRank for types. Assuming none of this is lighting a fire big enough to attract volunteers, to prioritize, it seems to me that this would be amenable to some UX research. (@kevmoo?) Which is most important is fairly subjective and for me, probably biased to my particular approach to coding in Dart. I'm guessing that's true for most of us who've been in the ecosystem a while.