diff options
| author | Mathew Inwood <mathewi@google.com> | 2018-12-07 11:15:49 +0000 |
|---|---|---|
| committer | Mathew Inwood <mathewi@google.com> | 2018-12-10 12:42:41 +0000 |
| commit | f653d935679f433ca05d1a6ef6f2d77fb49c27f3 (patch) | |
| tree | 0f3d338b5a360dccd32f7299bfdae7fcdd743046 /core/java/android | |
| parent | 385c42a2e9431fd345d42be57a21f03308f0fdec (diff) | |
Improve @UnsupportedAppUsage docs.
Add some words aimed at app developers, to help ensure that devs are
aware of the implications of using annotated members. Also add a link
to the public info on non-SDK interfaces, which includes a feature
request link.
Also use the term "non-SDK interface" in the docs as this is what is
used externally in the blog posts.
Test: m
Change-Id: I936e53082e308f484dfd42ba56a3575b78b6d3aa
Diffstat (limited to 'core/java/android')
| -rw-r--r-- | core/java/android/annotation/UnsupportedAppUsage.java | 24 |
1 files changed, 20 insertions, 4 deletions
diff --git a/core/java/android/annotation/UnsupportedAppUsage.java b/core/java/android/annotation/UnsupportedAppUsage.java index 28145a06ecf2..431a35ab9568 100644 --- a/core/java/android/annotation/UnsupportedAppUsage.java +++ b/core/java/android/annotation/UnsupportedAppUsage.java @@ -24,16 +24,32 @@ import java.lang.annotation.Retention; import java.lang.annotation.Target; /** - * Indicates that a class member, that is not part of the SDK, is used by apps. - * Since the member is not part of the SDK, such use is not supported. + * Indicates that this non-SDK interface is used by apps. A non-SDK interface is a + * class member (field or method) that is not part of the public SDK. Since the + * member is not part of the SDK, usage by apps is not supported. * - * <p>This annotation acts as a heads up that changing a given method or field + * <h2>If you are an Android App developer</h2> + * + * This annotation indicates that you may be able to access the member, but that + * this access is discouraged and not supported by Android. If there is a value + * for {@link #maxTargetSdk()} on the annotation, access will be restricted based + * on the {@code targetSdkVersion} value set in your manifest. + * + * <p>Fields and methods annotated with this are likely to be restricted, changed + * or removed in future Android releases. If you rely on these members for + * functionality that is not otherwise supported by Android, consider filing a + * <a href="http://g.co/dev/appcompat">feature request</a>. + * + * <h2>If you are an Android OS developer</h2> + * + * This annotation acts as a heads up that changing a given method or field * may affect apps, potentially breaking them when the next Android version is * released. In some cases, for members that are heavily used, this annotation * may imply restrictions on changes to the member. * * <p>This annotation also results in access to the member being permitted by the - * runtime, with a warning being generated in debug builds. + * runtime, with a warning being generated in debug builds. Which apps can access + * the member is determined by the value of {@link #maxTargetSdk()}. * * <p>For more details, see go/UnsupportedAppUsage. * |