Report exported member access on @deprecated export

[DartBot]

This issue was originally filed by @seaneagan

---

If you want to stop exporting library A from library B, but you don't want to deprecate library A itself, it would be nice to be able mark the export as deprecated:

@deprecated('Use libraryA.dart directly instead')
export 'libraryA.dart';

Here are some use cases:

Stop exporting something:
  dart-lang/test#53

Split part of a library into a separate library with a temporary re-export:
  dart-lang/test#2326

[bwilkerson]

Removed Priority-Unassigned label.
Added Priority-Medium, Area-Analyzer, Triaged labels.

[nex3]

I'd really appreciate this as well.

[srawlins]

In the following example:

import "package:test/test.dart";

void main() {
  test("String.split() splits the string on the delimiter", () {
    var string = "foo,bar,baz";
    expect(string.split(","), equals(["foo", "bar", "baz"]));
  });
}

What element would get the warning? equals() is an element whose library (package:matcher/matcher.dart) was is available because of its export in package:test/test.dart. Does the warning stick to equals? This makes sense to me, but the wording would have to be very clear, so that users aren't super confused when one day they bump their test package, and their analyzer, and now there are 200 warnings in their tests.

[nex3]

Yes, if test's export of matcher were deprecated, the equals() call would have the warning. I don't think the wording needs to be much more than just "equals() is deprecated"—from the user's perspective, it's the API that's deprecated, and they don't really care where the @deprecated annotation is.

Also, to be clear, test is not actually planning to deprecate its export of matcher.

[bwilkerson]

I suspect that the intent of putting a @deprecated annotation on an export is not to mark the API being exported as being deprecated, but rather to indicate that the export will be removed in a future version and hence users should switch to importing the original source of the API. If that's true, then the message should be something more like: "The function ... should be imported from ... rather than ...".

[lrhn]

I can see both intentions being correct in different cases.
It depends on whether the user is expected to keep using the functionality from the exported library or not. If the exported library is public, and it's not being deprecated itself, then it's likely that the user will begin importing it instead.

If the library is "private" (in lib/src/) then the user will likely not begin using it directly (but may use it indirectly if it's also exported by another public library). In either case, you are in control of the exported library as well, and could potentially make it deprecated.

I think the former case is the more likely, and the message could be "the function .. is deprecated as part of ... library. It may be imported as ... library instead.".