Merge "Add publicAlternatives to @UnsupportedAppUsage"

am: 2ac6496fb8

Change-Id: I73939680b531f32e54e62e7f50f7d75d364eefda

core/java/android/annotation/UnsupportedAppUsage.java

@@ -124,6 +124,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.
      */