Support `androidx.annotation.RestrictTo` annotation

[Jonathan Pobst]

Context: https://developer.android.com/reference/androidx/annotation/RestrictTo
Context: xamarin/AndroidX#690

Android has an annotation androidx.annotation.RestrictTo (@RestrictTo) that essentially means "this API is implemented as public, but we do not consider it public API". This means that Google reserves the right to change it at any time (see xamarin/AndroidX#690). Because we simply bind the API as public, it misleads our users into thinking this is a stable API they can rely on.

Example

In androidx.appcompat.appcompat-resources 1.6.0, Google decided to promote classes that were previously marked as @RestrictTo({RestrictTo.Scope.LIBRARY_GROUP_PREFIX}) to full public supported classes. However, when they did this they changed the names of the classes, breaking our users (including XF) who were using the "internal" classes.

1.5.1

1.6.0

Proposal

We should do something to help protect our users from this scenario. I am not currently aware of any "public but not really" construct in .NET, so we may have to get creative to come up with something.

One idea would be to (ab)use [Obsolete] with a custom warning code and message to explain the risk to users, while providing them a warning code they can suppress:

[Obsolete ("While this type is public, Google considers it internal API and reserves the right to modify or delete it in the future. Use at your own risk."), DiagnosticId = "XAxxxx"]
public class AndroidX.AppCompat.Graphics.Drawable.DrawableWrapper { ... }

A potential wrinkle is a type/member cannot contain multiple [Obsolete] attributes, so we will have to guard against that if it is obsolete for another reason.

Another option would be to do essentially the same thing with our own custom attribute and a Roslyn analyzer.