Android/frameworks_base
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Improve @UnsupportedAppUsage docs.

Browse Source 
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
This commit is contained in:
Mathew Inwood
2018-12-07 11:15:49 +00:00
parent 385c42a2e9
commit f653d93567
1 changed files with 20 additions and 4 deletions
Download Patch File Download Diff File Expand all files Collapse all files

24
core/java/android/annotation/UnsupportedAppUsage.java
View File

@@ -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.
*