From da8ef6e5a3c1390bec4d8d3ef2bbbe4bf80c4c13 Mon Sep 17 00:00:00 2001
From: Ameer Armaly <aarmaly@google.com>
Date: Wed, 16 Feb 2022 15:49:19 -0800
Subject: [PATCH] Fix speech state event javadocs per API review.

Fix: 219740393
Test: N/A
Change-Id: I1b3be67cdb3986426ef83726ebbc316654012996
(cherry picked from commit c025739eda1d491727569a6a8ebe3fdfce5c49eb)
---
 .../accessibility/AccessibilityEvent.java     | 43 ++++++++++++++++---
 1 file changed, 36 insertions(+), 7 deletions(-)

diff --git a/core/java/android/view/accessibility/AccessibilityEvent.java b/core/java/android/view/accessibility/AccessibilityEvent.java
index 7e16531663d54..cd0dd1df12496 100644
--- a/core/java/android/view/accessibility/AccessibilityEvent.java
+++ b/core/java/android/view/accessibility/AccessibilityEvent.java
@@ -384,6 +384,25 @@ import java.util.List;
  *   <li>{@link #getEventTime()}  - The event time.</li>
  *   <li>{@link #getText()} - The text of the announcement.</li>
  * </ul>
+ * </p>
+  * <p>
+ * <b>speechStateChanged</b>
+ * <em>Type:</em> {@link #TYPE_SPEECH_STATE_CHANGE}</br>
+ * Represents a change in the speech state defined by the
+ * bit mask of the speech state change types.
+ * A change in the speech state occurs when an application wants to signal that
+ * it is either speaking or listening for human speech.
+ * This event helps avoid conflicts where two applications want to speak or one listens
+ * when another speaks.
+ * When sending this event, the sender should ensure that  the accompanying state change types
+ * make sense. For example, the sender should not send
+ * {@link #SPEECH_STATE_SPEAKING_START} and {@link #SPEECH_STATE_SPEAKING_END} together.
+ * <em>Properties:</em></br>
+ * <ul>
+ *   <li>{@link #getSpeechStateChangeTypes()} - The type of state changes</li>
+ *   <li>{@link #getPackageName()} - The package name of the source.</li>
+ *   <li>{@link #getEventTime()}  - The event time.</li>
+ * </ul>
  * </p>
  *
  * @see android.view.accessibility.AccessibilityManager
@@ -553,14 +572,20 @@ public final class AccessibilityEvent extends AccessibilityRecord implements Par
     public static final int TYPE_ASSIST_READING_CONTEXT = 0x01000000;
 
     /**
-     * Represents a change in the speech state defined by the content-change types. A change in the
-     * speech state occurs when another service is either speaking or listening for human speech.
-     * This event helps avoid conflicts where two services want to speak or one listens
+     * Represents a change in the speech state defined by the speech state change types.
+     * A change in the speech state occurs when an application wants to signal that it is either
+     * speaking or listening for human speech.
+     * This event helps avoid conflicts where two applications want to speak or one listens
      * when another speaks.
+     * When sending this event, the sender should ensure that  the accompanying state change types
+     * make sense. For example, the sender should not send
+     * {@link #SPEECH_STATE_SPEAKING_START} and {@link #SPEECH_STATE_SPEAKING_END} together.
      * @see #SPEECH_STATE_SPEAKING_START
      * @see #SPEECH_STATE_SPEAKING_END
      * @see #SPEECH_STATE_LISTENING_START
      * @see #SPEECH_STATE_LISTENING_END
+     * @see #getSpeechStateChangeTypes
+     * @see #setSpeechStateChangeTypes
      */
     public static final int TYPE_SPEECH_STATE_CHANGE = 0x02000000;
 
@@ -1067,7 +1092,7 @@ public final class AccessibilityEvent extends AccessibilityRecord implements Par
     }
 
     /**
-     * Gets the speech state signaled by a {@link #TYPE_SPEECH_STATE_CHANGE} event
+     * Gets the bit mask of the speech state signaled by a {@link #TYPE_SPEECH_STATE_CHANGE} event
      *
      * @see #SPEECH_STATE_SPEAKING_START
      * @see #SPEECH_STATE_SPEAKING_END
@@ -1078,7 +1103,7 @@ public final class AccessibilityEvent extends AccessibilityRecord implements Par
         return mSpeechStateChangeTypes;
     }
 
-    private static String speechStateChangedTypesToString(int types) {
+    private static String speechStateChangeTypesToString(int types) {
         return BitUtils.flagsToString(
                 types, AccessibilityEvent::singleSpeechStateChangeTypeToString);
     }
@@ -1099,14 +1124,18 @@ public final class AccessibilityEvent extends AccessibilityRecord implements Par
     }
 
     /**
-     * Sets the speech state type signaled by a {@link #TYPE_SPEECH_STATE_CHANGE} event
+     * Sets the bit mask of the speech state change types
+     * signaled by a {@link #TYPE_SPEECH_STATE_CHANGE} event.
+     * The sender is responsible for ensuring that  the state change types  make sense. For example,
+     * the sender should not send
+     * {@link #SPEECH_STATE_SPEAKING_START} and {@link #SPEECH_STATE_SPEAKING_END} together.
      *
      * @see #SPEECH_STATE_SPEAKING_START
      * @see #SPEECH_STATE_SPEAKING_END
      * @see #SPEECH_STATE_LISTENING_START
      * @see #SPEECH_STATE_LISTENING_END
      */
-    public void setSpeechStateChangeTypes(int state) {
+    public void setSpeechStateChangeTypes(@SpeechStateChangeTypes int state) {
         enforceNotSealed();
         mSpeechStateChangeTypes = state;
     }