Merge "Add publicAlternatives to @UnsupportedAppUsage"

1 files changed, 26 insertions, 0 deletions

diff --git a/core/java/android/annotation/UnsupportedAppUsage.java b/core/java/android/annotation/UnsupportedAppUsage.java
index ac3daaf638ad..a454df5d68f4 100644
--- a/core/java/android/annotation/UnsupportedAppUsage.java
+++ b/core/java/android/annotation/UnsupportedAppUsage.java
@@ -125,6 +125,32 @@ public @interface UnsupportedAppUsage {
     String implicitMember() default "";
 
     /**
+     * Public API alternatives to this API.
+     *
+     * <p>If non-empty, the string must be a description of the public API alternative(s) to this
+     * API. The explanation must contain at least one Javadoc link tag to public API methods or
+     * fields. e.g.:
+     * {@literal @UnsupportedAppUsage(publicAlternatives="Use {@link foo.bar.Baz#bat()} instead.")}
+     *
+     * <p>Any elements that can be deduced can be omitted, e.g.:
+     * <ul>
+     *      <li>
+     *          the class, if it's the same as for the annotated element.
+     *      </li>
+     *      <li>
+     *          the package name, if it's the same as for the annotated element.
+     *      </li>
+     *      <li>
+     *          the method parameters, if there is only one method with that name in the given
+     *          package and class.
+     *      </li>
+     * </ul>
+     * @return A Javadoc-formatted string.
+     */
+    @SuppressWarnings("JavadocReference")
+    String publicAlternatives() default "";
+
+    /**
      * Container for {@link UnsupportedAppUsage} that allows it to be applied repeatedly to types.
      */
     @Retention(CLASS)