From cd6bf71ced543f9267b2845b84693c674fbd3e95 Mon Sep 17 00:00:00 2001
From: Galia Peycheva <galinap@google.com>
Date: Tue, 8 Feb 2022 18:12:32 +0100
Subject: [PATCH] Add a note to preferKeepClear APIs documentation

Bug: 216590903
Test: m doc-comment-check-docs
Change-Id: Ic696694edfea4bd9c0bb88d6851b2932427b757d
---
 core/java/android/view/View.java | 11 +++++++----
 core/res/res/values/attrs.xml    |  2 +-
 2 files changed, 8 insertions(+), 5 deletions(-)

diff --git a/core/java/android/view/View.java b/core/java/android/view/View.java
index 22c66dc7aee69..352ec599ddb05 100644
--- a/core/java/android/view/View.java
+++ b/core/java/android/view/View.java
@@ -11763,7 +11763,10 @@ public class View implements Drawable.Callback, KeyEvent.Callback,
      * user and that ideally it should not be covered. Setting this is only appropriate for UI
      * where the user would likely take action to uncover it.
      * <p>
-     * The system will try to respect this, but when not possible will ignore it.
+     * The system will try to respect this preference, but when not possible will ignore it.
+     * <p>
+     * Note: while this is set to {@code true}, the system will ignore the {@code Rect}s provided
+     * through {@link #setPreferKeepClearRects} (but not clear them).
      * <p>
      * @see #setPreferKeepClearRects
      * @see #isPreferKeepClear
@@ -11795,11 +11798,11 @@ public class View implements Drawable.Callback, KeyEvent.Callback,
      * user and that ideally they should not be covered. Setting this is only appropriate for UI
      * where the user would likely take action to uncover it.
      * <p>
-     * If the whole view is preferred to be clear ({@link #isPreferKeepClear}), the rects set here
-     * will be ignored.
-     * <p>
      * The system will try to respect this preference, but when not possible will ignore it.
      * <p>
+     * Note: While {@link #isPreferKeepClear} is {@code true}, the {@code Rect}s set here are
+     * ignored.
+     * <p>
      * @see #setPreferKeepClear
      * @see #getPreferKeepClearRects
      */
diff --git a/core/res/res/values/attrs.xml b/core/res/res/values/attrs.xml
index d774fd4e397a7..a92a2b8498474 100644
--- a/core/res/res/values/attrs.xml
+++ b/core/res/res/values/attrs.xml
@@ -3353,7 +3353,7 @@
             area for the user and that ideally it should not be covered. Setting this is only
             appropriate for UI where the user would likely take action to uncover it.
             <p>The system will try to respect this, but when not possible will ignore it.
-            See {@link android.view.View#setPreferKeepClear}. -->
+            <p>This is equivalent to {@link android.view.View#setPreferKeepClear}.-->
         <attr name="preferKeepClear" format="boolean" />
 
         <!-- <p>Whether or not the auto handwriting initiation is enabled in this View.