Add forAutoFill suffix on ViewStructure methods that add children.

Change-Id: I36f7bd26b7d45fd809d7398cc86de3d2671f2b28
Fixes: 35764877
Test: m update-api

1 files changed, 26 insertions, 10 deletions

diff --git a/core/java/android/view/ViewStructure.java b/core/java/android/view/ViewStructure.java
index bc0960c62c62..92f78b9301c0 100644
--- a/core/java/android/view/ViewStructure.java
+++ b/core/java/android/view/ViewStructure.java
@@ -258,20 +258,25 @@ public abstract class ViewStructure {
     /**
      * Create a new child {@link ViewStructure} in this view, putting into the list of
      * children at <var>index</var>.
+     *
      * @return Returns an fresh {@link ViewStructure} ready to be filled in.
      */
     public abstract ViewStructure newChild(int index);
 
     /**
-     * Like {@link #newChild(int)}, but providing a {@code virtualId} to the child so it can be
-     * auto-filled by {@link View#autoFillVirtual(int, AutoFillValue)}.
+     * Create a new child {@link ViewStructure} in this view for auto-fill purposes.
      *
-     * @param index child index
-     * @param virtualId id identifying the virtual child inside the custom view.
+     * @param index the index (in the list of children) to put the new child at (see
+     *            {@link #addChildCount(int)} and {@link #setChildCount(int)}.
+     * @param virtualId an opaque ID to the Android System (although it could be meaningful to the
+     *            {@link View} creating the {@link ViewStructure}), but it's the same id used on
+     *            {@link View#autoFillVirtual(int, AutoFillValue)}.
      * @param flags currently {@code 0}.
+     *
+     * @return Returns an fresh {@link ViewStructure} ready to be filled in.
      */
     // TODO(b/33197203, b/33802548): add CTS/unit test
-    public abstract ViewStructure newChild(int index, int virtualId, int flags);
+    public abstract ViewStructure newChildForAutoFill(int index, int virtualId, int flags);
 
     /**
      * Like {@link #newChild}, but allows the caller to asynchronously populate the returned
@@ -284,15 +289,26 @@ public abstract class ViewStructure {
     public abstract ViewStructure asyncNewChild(int index);
 
     /**
-     * Like {@link #asyncNewChild(int)}, but providing a {@code virtualId} to the child so it can be
-     * auto-filled by {@link View#autoFillVirtual(int, AutoFillValue)}.
+     * Like {@link #newChildForAutoFill(int, int, int)}, but allows the caller to asynchronously
+     * populate the returned child.
+     *
+     * <p>It can transfer the returned {@link ViewStructure} to another thread for it to build its
+     * content (and children etc).
      *
-     * @param index child index
-     * @param virtualId id identifying the virtual child inside the custom view.
+     * <p>Once done, some thread must call {@link #asyncCommit()} to tell the containing
+     * {@link ViewStructure} that the async population is done.
+     *
+     * @param index the index (in the list of children) to put the new child at (see
+     *            {@link #addChildCount(int)} and {@link #setChildCount(int)}.
+     * @param virtualId an opaque ID to the Android System (although it could be meaningful to the
+     *            {@link View} creating the {@link ViewStructure}), but it's the same id used on
+     *            {@link View#autoFillVirtual(int, AutoFillValue)}.
      * @param flags currently {@code 0}.
+     *
+     * @return Returns an fresh {@link ViewStructure} ready to be filled in.
      */
     // TODO(b/33197203, b/33802548): add CTS/unit test
-    public abstract ViewStructure asyncNewChild(int index, int virtualId, int flags);
+    public abstract ViewStructure asyncNewChildForAutoFill(int index, int virtualId, int flags);
 
     /**
      * Sets the {@link AutoFillType} that can be used to auto-fill this node.