From e93fe8da7867c05e31738813bbe51f5023bf2fad Mon Sep 17 00:00:00 2001
From: Sally Yuen <sallyyuen@google.com>
Date: Fri, 2 Sep 2022 23:35:41 +0000
Subject: [PATCH] Update View#setContentDescription to advise not setting type
 or state

Bug: 244787982
Test: n/a
Change-Id: Icf2ae256bae7febe7e6750aa9b5dec66968d3883
---
 core/java/android/view/View.java | 11 +++++++++++
 1 file changed, 11 insertions(+)

diff --git a/core/java/android/view/View.java b/core/java/android/view/View.java
index 996dee0cd2da4..bc6d7c8fa6d64 100644
--- a/core/java/android/view/View.java
+++ b/core/java/android/view/View.java
@@ -10993,8 +10993,19 @@ public class View implements Drawable.Callback, KeyEvent.Callback,
      * description. An image of a floppy disk that is used to save a file may
      * use "Save".
      *
+     * <p>
+     * This should omit role or state. Role refers to the kind of user-interface element the View
+     * is, such as a Button or Checkbox. State refers to a frequently changing property of the View,
+     * such as an On/Off state of a button or the audio level of a volume slider.
+     *
+     * <p>
+     * Content description updates are not frequent, and are used when the semantic content - not
+     * the state - of the element changes. For example, a Play button might change to a Pause
+     * button during music playback.
+     *
      * @param contentDescription The content description.
      * @see #getContentDescription()
+     * @see #setStateDescription(CharSequence)} for state changes.
      * @attr ref android.R.styleable#View_contentDescription
      */
     @RemotableViewMethod