In Flutter docs, classes are listed multiple times

[Hixie]

When a library exports another library, but both libraries are being docced together, the result is that each class that is exported by both libraries is listed twice.

We should only list classes as coming from the package that they actually come from, and not mention them in packages that re-export them, if we are including that package in the docs.

See also:

• don't link to exported name if original location is public and inside same package #1090 (about where the links to reexported symbols should point)
• Exported classes don't have any indication where they come from #936 (about saying where types come from when reexported)
• For Flutter docs, be more aggressive about including dependencies #1159 (about automatically documenting even non-exported libraries)

cc @devoncarew

[devoncarew]

also adding @keertip

[abarth]

As an example, the BoxDecoration class has four different URLs:

https://docs.flutter.io/flutter/painting/BoxDecoration-class.html
https://docs.flutter.io/flutter/rendering/BoxDecoration-class.html
https://docs.flutter.io/flutter/widgets/BoxDecoration-class.html
https://docs.flutter.io/flutter/material/BoxDecoration-class.html

It's not obvious that these are the same class. If there was a canonical URL that all the re-exports linked to, that would make that much clearer.

[astashov]

I will look at it.

[astashov]

We should only list classes as coming from the package that they actually come from, and not mention them in packages that re-export them, if we are including that package in the docs.

Hmm, how do we know what's the "canonical" library? I.e. library foo and library bar both export lib/src/blah.dart with foobar function, what library docs will contain that foobar function? foo or bar?

It's not obvious that these are the same class. If there was a canonical URL that all the re-exports linked to, that would make that much clearer.

Yeah, we can do that, the question is - how do we know which one is canonical? Just the first one encountered during parsing?

[abarth]

That isn't what's happening here. What's happening here is:

1. A defines Foo.
2. Foo doesn't appear in the docs for A because A is a private library, i.e., in lib/src/../a.dart
3. B exports Foo from A.
4. Foo appears in the docs for B.
5. C exports Foo from B.
6. Foo appears in the docs for C.

The issue is at step (6) above. Specifically, Foo shouldn't appear in the docs for C (or at least should be de-emphasized in some way) because Foo was exported from B and B already has docs.

[astashov]

Aha, I see, thanks.

[keertip]

From the example above, since C does export Foo, Foo will appear in the docs for C, and that's the way it should be, as Foo is now part of the public api for C. The issue here is that Foo is defined in B, so maybe we can we have some indication that Foo is from B, or as abarth@ mentioned, de-emphasize it in the UI.

[Hixie]

For Flutter, what we want is that Foo is hidden (or at least dramatically de-emphasised, including not appearing in the search and not having its own page) from the public API of C in the docs. It's fine if the docs for it in the context of B say that they're also exported from C.