Improved documentation and added @CallSuper on onProvideAutoFillStructure().

onProvideAutoFillStructure() sets mandatory auto-fill information like the
auto-fill id, so we must enforce subclass to call it.

Bug: 35395043
Test: m update-api
Change-Id: I525690b38639d970f516a906ddeb3a6bd6e01d8c

core/java/android/app/assist/AssistStructure.java

@@ -1059,6 +1059,10 @@ public class AssistStructure implements Parcelable {
          * <li>Root node (containing the URL of the HTML page)
          * <li>Child nodes that represent hyperlinks (contains the hyperlink URL).
          * </ol>
+         *
+         * <strong>WARNING:</strong> a {@link android.service.autofill.AutoFillService} should only
+         * use this URL for auto-fill purposes when it trusts the app generating it (i.e., the app
+         * defined by {@link AssistStructure#getActivityComponent()}).
          */
         public String getUrl() {
             return mUrl;

core/java/android/view/View.java

@@ -6983,19 +6983,15 @@ public class View implements Drawable.Callback, KeyEvent.Callback,
     /**
      * Called when assist structure is being retrieved from a view as part of an auto-fill request.
      *
-     * <p>When implementing this method, subclasses must also:
-     *
-     * <ol>
-     * <li>Implement {@link #autoFill(AutoFillValue)}, {@link #getAutoFillType()}
-     * and {@link #getAutoFillValue()}.
-     * <li>Call {@link android.view.autofill.AutoFillManager#virtualValueChanged(View, int,
-     * AutoFillValue)} when its value changed.
-     * </ol>
+     * <p>This method already provides most of what's needed for auto-fill, but should be overridden
+     * when the view contents does not include PII (Personally Identifiable Information) (so it
+     * can call {@link ViewStructure#setSanitized(boolean) ViewStructure#setSanitized(true)}).
      *
      * @param structure Fill in with structured view data. The default implementation
      * fills in all data that can be inferred from the view itself.
      * @param flags optional flags (currently {@code 0}).
      */
+    @CallSuper
     public void onProvideAutoFillStructure(ViewStructure structure, int flags) {
         onProvideStructureForAssistOrAutoFill(structure, true);
     }