Cross-link extensions on class where they apply

[munificent]

Issue #2001 is about documenting extensions themselves at the point they are defined. That's canonical "place" for an extension's docs.

One concern some users have is that users will run into this scenario.

1. They see some code like foo.bar(). They want to know what bar() is.
2. They know foo is a Foo, so they look up the API docs for Foo.
3. No bar().

What they don't realize is that bar() is an extension method defined elsewhere. In the general case, this can't be solved. Users can define extensions on types outside of their own packages, even on core library types or non-class types that have no docs.

But in many cases, the type the extension applies to is a class in the same package where the extension itself is defined. In those cases, it would be nice if the dartdoc for that class could cross-link to the relevant extensions. For example, the C# docs for the IEnumerable interface have a section for extension methods the .NET core library defines on that type.

cc @mit-mit

[jcollins-g]

Cases like our dart:ffi's Pointer, where extension methods are being used as a primitive sort of method overloading, may require some additional thought as expanding all possible methods on the class page could be unreadable. A followup to #2053 will have a first pass idea of what that might look like.

[parlough]

As more and more SDK methods are being added as extensions, it's getting more important to flesh out (and implement) a design for this. Including how to handle cases like the dart:ffi Pointer ones that Janice mentioned earlier. This could perhaps be a new section for extension methods, then a dropdown for extension methods with the same name?

DateTime.copyWith is a recent example of being hard to discover (as illustrated by dart-lang/sdk#53729):

I don't think people will think to look at the DateTime extensions, then dive into a specific one to learn more, making it quite impossible to discover.

Edit: I think this would be an interesting issue for someone looking to start contributing to Dart to take on. I reached out to a few people but if anyone is interested in working on this, consider responding here. I'd be happy to help if needed (as much as I can 🙈).