Merge "Prepare comments and annotations for OverlayInfo & OverlayIdentifier public API"

3 files changed, 99 insertions, 24 deletions

diff --git a/core/api/system-current.txt b/core/api/system-current.txt
index 99aa01f98e9b..1eed2d4c0d6d 100644
--- a/core/api/system-current.txt
+++ b/core/api/system-current.txt
@@ -3432,7 +3432,7 @@ package android.content.om {
     method @NonNull public String getTargetPackageName();
     method public int getUserId();
     method public boolean isEnabled();
-    method public void writeToParcel(android.os.Parcel, int);
+    method public void writeToParcel(@NonNull android.os.Parcel, int);
     field @NonNull public static final android.os.Parcelable.Creator<android.content.om.OverlayInfo> CREATOR;
   }
 
diff --git a/core/java/android/content/om/OverlayIdentifier.java b/core/java/android/content/om/OverlayIdentifier.java
index 454d0d120f2f..a43091e6d5e2 100644
--- a/core/java/android/content/om/OverlayIdentifier.java
+++ b/core/java/android/content/om/OverlayIdentifier.java
@@ -27,32 +27,44 @@ import java.util.Objects;
 
 /**
  * A key used to uniquely identify a Runtime Resource Overlay (RRO).
+ * <!-- For applications -->
  *
- * An overlay always belongs to a package and may optionally have a name associated with it.
- * The name helps uniquely identify a particular overlay within a package.
- * @hide
+ * <p>An overlay always belongs to a package and have a mandatory name associated with it. The name
+ * helps uniquely identify a particular overlay within a package.
+ *
+ * <!-- For OverlayManagerService, it isn't public part and hidden by HTML comment. -->
+ * <!--
+ * <p>An overlay always belongs to a package and may optionally have a name associated with it. The
+ * name helps uniquely identify a particular overlay within a package.
+ * -->
+ *
+ * @see OverlayInfo#getOverlayIdentifier()
+ * @see OverlayManagerTransaction.Builder#unregisterFabricatedOverlay(OverlayIdentifier)
  */
 /** @hide */
 @DataClass(genConstructor = false, genBuilder = false, genHiddenBuilder = false,
         genEqualsHashCode = true, genToString = false)
-public class OverlayIdentifier implements Parcelable  {
+public final class OverlayIdentifier implements Parcelable {
     /**
      * The package name containing or owning the overlay.
+     *
+     * @hide
      */
-    @Nullable
-    private final String mPackageName;
+    @Nullable private final String mPackageName;
 
     /**
      * The unique name within the package of the overlay.
+     *
+     * @hide
      */
-    @Nullable
-    private final String mOverlayName;
+    @Nullable private final String mOverlayName;
 
     /**
      * Creates an identifier from a package and unique name within the package.
      *
      * @param packageName the package containing or owning the overlay
      * @param overlayName the unique name of the overlay within the package
+     * @hide
      */
     public OverlayIdentifier(@NonNull String packageName, @Nullable String overlayName) {
         mPackageName = packageName;
@@ -63,18 +75,24 @@ public class OverlayIdentifier implements Parcelable  {
      * Creates an identifier for an overlay without a name.
      *
      * @param packageName the package containing or owning the overlay
+     * @hide
      */
     public OverlayIdentifier(@NonNull String packageName) {
         mPackageName = packageName;
         mOverlayName = null;
     }
 
+    /**
+     * {@inheritDoc}
+     * @hide
+     */
     @Override
     public String toString() {
         return mOverlayName == null ? mPackageName : mPackageName + ":" + mOverlayName;
     }
 
     /** @hide */
+    @NonNull
     public static OverlayIdentifier fromString(@NonNull String text) {
         final String[] parts = text.split(":", 2);
         if (parts.length == 2) {
@@ -86,7 +104,7 @@ public class OverlayIdentifier implements Parcelable  {
 
 
 
-    // Code below generated by codegen v1.0.22.
+    // Code below generated by codegen v1.0.23.
     //
     // DO NOT MODIFY!
     // CHECKSTYLE:OFF Generated code
@@ -101,6 +119,8 @@ public class OverlayIdentifier implements Parcelable  {
 
     /**
      * Retrieves the package name containing or owning the overlay.
+     *
+     * @hide
      */
     @DataClass.Generated.Member
     public @Nullable String getPackageName() {
@@ -109,12 +129,18 @@ public class OverlayIdentifier implements Parcelable  {
 
     /**
      * Retrieves the unique name within the package of the overlay.
+     *
+     * @hide
      */
     @DataClass.Generated.Member
     public @Nullable String getOverlayName() {
         return mOverlayName;
     }
 
+    /**
+     * {@inheritDoc}
+     * @hide
+     */
     @Override
     @DataClass.Generated.Member
     public boolean equals(@Nullable Object o) {
@@ -132,6 +158,10 @@ public class OverlayIdentifier implements Parcelable  {
                 && Objects.equals(mOverlayName, that.mOverlayName);
     }
 
+    /**
+     * {@inheritDoc}
+     * @hide
+     */
     @Override
     @DataClass.Generated.Member
     public int hashCode() {
@@ -144,6 +174,10 @@ public class OverlayIdentifier implements Parcelable  {
         return _hash;
     }
 
+    /**
+     * {@inheritDoc}
+     * @hide
+     */
     @Override
     @DataClass.Generated.Member
     public void writeToParcel(@NonNull Parcel dest, int flags) {
@@ -158,6 +192,10 @@ public class OverlayIdentifier implements Parcelable  {
         if (mOverlayName != null) dest.writeString(mOverlayName);
     }
 
+    /**
+     * {@inheritDoc}
+     * @hide
+     */
     @Override
     @DataClass.Generated.Member
     public int describeContents() { return 0; }
@@ -165,7 +203,7 @@ public class OverlayIdentifier implements Parcelable  {
     /** @hide */
     @SuppressWarnings({"unchecked", "RedundantCast"})
     @DataClass.Generated.Member
-    protected OverlayIdentifier(@NonNull Parcel in) {
+    /* package-private */ OverlayIdentifier(@NonNull Parcel in) {
         // You can override field unparcelling by defining methods like:
         // static FieldType unparcelFieldName(Parcel in) { ... }
 
@@ -194,10 +232,10 @@ public class OverlayIdentifier implements Parcelable  {
     };
 
     @DataClass.Generated(
-            time = 1612482438728L,
-            codegenVersion = "1.0.22",
+            time = 1670404485646L,
+            codegenVersion = "1.0.23",
             sourceFile = "frameworks/base/core/java/android/content/om/OverlayIdentifier.java",
-            inputSignatures = "private final @android.annotation.Nullable java.lang.String mPackageName\nprivate final @android.annotation.Nullable java.lang.String mOverlayName\npublic @java.lang.Override java.lang.String toString()\npublic static  android.content.om.OverlayIdentifier fromString(java.lang.String)\nclass OverlayIdentifier extends java.lang.Object implements [android.os.Parcelable]\n@com.android.internal.util.DataClass(genConstructor=false, genBuilder=false, genHiddenBuilder=false, genEqualsHashCode=true, genToString=false)")
+            inputSignatures = "private final @android.annotation.Nullable java.lang.String mPackageName\nprivate final @android.annotation.Nullable java.lang.String mOverlayName\npublic @java.lang.Override java.lang.String toString()\npublic static @android.annotation.NonNull android.content.om.OverlayIdentifier fromString(java.lang.String)\nclass OverlayIdentifier extends java.lang.Object implements [android.os.Parcelable]\n@com.android.internal.util.DataClass(genConstructor=false, genBuilder=false, genHiddenBuilder=false, genEqualsHashCode=true, genToString=false)")
     @Deprecated
     private void __metadata() {}
 
diff --git a/core/java/android/content/om/OverlayInfo.java b/core/java/android/content/om/OverlayInfo.java
index a470de2db8fd..a81d16ab4ca3 100644
--- a/core/java/android/content/om/OverlayInfo.java
+++ b/core/java/android/content/om/OverlayInfo.java
@@ -33,9 +33,19 @@ import java.lang.annotation.RetentionPolicy;
 import java.util.Objects;
 
 /**
+ * An immutable information about an overlay.
+ *
+ * <p>Applications calling {@link OverlayManager#getOverlayInfosForTarget(String)} get the
+ * information list of the registered overlays. Each element in the list presents the information of
+ * the particular overlay.
+ *
+ * <!-- For OverlayManagerService, it isn't public part and hidden by HTML comment. -->
+ * <!--
  * Immutable overlay information about a package. All PackageInfos that
  * represent an overlay package will have a corresponding OverlayInfo.
+ * -->
  *
+ * @see OverlayManager#getOverlayInfosForTarget(String)
  * @hide
  */
 @SystemApi
@@ -174,14 +184,14 @@ public final class OverlayInfo implements CriticalOverlayInfo, Parcelable {
      *
      * @hide
      */
-    public final String targetOverlayableName;
+    @Nullable public final String targetOverlayableName;
 
     /**
      * Category of the overlay package
      *
      * @hide
      */
-    public final String category;
+    @Nullable public final String category;
 
     /**
      * Full path to the base APK for this overlay package
@@ -272,7 +282,7 @@ public final class OverlayInfo implements CriticalOverlayInfo, Parcelable {
     }
 
     /** @hide */
-    public OverlayInfo(Parcel source) {
+    public OverlayInfo(@NonNull Parcel source) {
         packageName = source.readString();
         overlayName = source.readString();
         targetPackageName = source.readString();
@@ -299,7 +309,9 @@ public final class OverlayInfo implements CriticalOverlayInfo, Parcelable {
     }
 
     /**
-     * {@inheritDoc}
+     * Get the overlay name from the registered fabricated overlay.
+     *
+     * @return the overlay name
      * @hide
      */
     @Override
@@ -309,7 +321,9 @@ public final class OverlayInfo implements CriticalOverlayInfo, Parcelable {
     }
 
     /**
-     * {@inheritDoc}
+     * Returns the name of the target overlaid package.
+     *
+     * @return the target package name
      * @hide
      */
     @Override
@@ -342,11 +356,13 @@ public final class OverlayInfo implements CriticalOverlayInfo, Parcelable {
     }
 
     /**
-     * {@inheritDoc}
+     * Return the target overlayable name.
+     *
+     * @return the name of the target overlayable resources set
      * @hide
      */
-    @Override
     @SystemApi
+    @Override
     @Nullable
     public String getTargetOverlayableName() {
         return targetOverlayableName;
@@ -366,12 +382,18 @@ public final class OverlayInfo implements CriticalOverlayInfo, Parcelable {
      *
      * @hide
      */
+    @NonNull
     public String getBaseCodePath() {
         return baseCodePath;
     }
 
     /**
-     * {@inheritDoc}
+     * Get the unique identifier from the overlay information.
+     *
+     * <p>The return value of this function can be used to unregister the related overlay.
+     *
+     * @return an identifier representing the current overlay.
+     * @see OverlayManagerTransaction.Builder#unregisterFabricatedOverlay(OverlayIdentifier)
      * @hide
      */
     @Override
@@ -415,7 +437,7 @@ public final class OverlayInfo implements CriticalOverlayInfo, Parcelable {
     }
 
     @Override
-    public void writeToParcel(Parcel dest, int flags) {
+    public void writeToParcel(@NonNull Parcel dest, int flags) {
         dest.writeString(packageName);
         dest.writeString(overlayName);
         dest.writeString(targetPackageName);
@@ -429,7 +451,7 @@ public final class OverlayInfo implements CriticalOverlayInfo, Parcelable {
         dest.writeBoolean(isFabricated);
     }
 
-    public static final @android.annotation.NonNull Parcelable.Creator<OverlayInfo> CREATOR =
+    public static final @NonNull Parcelable.Creator<OverlayInfo> CREATOR =
             new Parcelable.Creator<OverlayInfo>() {
         @Override
         public OverlayInfo createFromParcel(Parcel source) {
@@ -492,6 +514,11 @@ public final class OverlayInfo implements CriticalOverlayInfo, Parcelable {
         }
     }
 
+    /**
+     * {@inheritDoc}
+     *
+     * @hide
+     */
     @Override
     public int hashCode() {
         final int prime = 31;
@@ -508,6 +535,11 @@ public final class OverlayInfo implements CriticalOverlayInfo, Parcelable {
         return result;
     }
 
+    /**
+     * {@inheritDoc}
+     *
+     * @hide
+     */
     @Override
     public boolean equals(@Nullable Object obj) {
         if (this == obj) {
@@ -547,6 +579,11 @@ public final class OverlayInfo implements CriticalOverlayInfo, Parcelable {
         return true;
     }
 
+    /**
+     * {@inheritDoc}
+     *
+     * @hide
+     */
     @NonNull
     @Override
     public String toString() {