| commit | 2148219d795513065ef3dcfd7bdd9fc6aa623399 | [log] [tgz] |
|---|---|---|
| author | Tor Norbye <tnorbye@google.com> | Thu Feb 17 08:07:12 2022 -0800 |
| committer | Tor Norbye <tnorbye@google.com> | Thu Feb 17 08:07:12 2022 -0800 |
| tree | ea7b8f2b10ac23c5f1685f347d1e4767f43eb944 | |
| parent | e84d3847e8448a29ca0aecb87433c23bd484bab7 [diff] |
144111352: Create @DeprecatedForSdk annotation
This CL adds a new @DeprecatedForSdk annotation. This will be treated
as a normal deprecation annotations when generating signature and stub
files.
The purpose of this annotation is to let the framework annotate some
APIs as deprecated in the SDK without actually deprecating them within
the framework itself; an example of this would be ArrayMap where SDK
users should be using the androidx versions instead:
package android.util
@DeprecatedForSdk("Use androidx.collection.ArrayMap instead")
punlic class ArrayMap { ...
When metalava generates stubs for this, the ArrayMap class will instead
look like this:
package android.util
/** @deprecated Use androidx.collection.ArrayMap instead */
@Deprecated
punlic class ArrayMap { ...
However, the source code itself is not marked @Deprecated, so internal
framework usages of the API will not be flagged.
It will however be treated as deprecated in the public SDK, the system
SDK, the test SDK, and so on. When metalava is invoked with
--show-annotation android.annotation.SystemApi
(to generate the System API), it will also avoid marking stubs as
deprecated for any @DeprecatedForSdk annotations that specify an
`allowIn` target which includes `android.annotation.SystemApi`. This
makes it possible to deprecate APIs and specifically exempt API
surfaces like the system api or the test api; list each annotation
corresponding to an API surface as `allowedIn`.
Fixes: 144111352
Test: Unit test in metalava
Change-Id: I1492b6e1f94c6cc022d8585feb2a4f6ac81581d1
Libraries and utilities intended for use by module and framework code.
Since modules use the code in this project, it must adhere to mainline requirements, for example, by setting min_sdk_version in Soong modules.
This project uses a single source path for Java code. All Java code should go in the java directory with subdirectories corresponding to the java package. Android.bp files should go alongside the java source files, and should only include java source for a single java package to encourage good code hygiene.
Tests for java code should go in the javatests directory and follow the same structure.