From 33c7136dde17857bed452d0ddac37018869c7dab Mon Sep 17 00:00:00 2001
From: Phil Weaver <pweaver@google.com>
Date: Tue, 9 May 2017 16:17:02 -0700
Subject: [PATCH] Clarify documentation for notification a11y events

This javadoc was confusing the TalkBack team, so I've
clarified that these events can come from either a
notification or a toast. I also removed a note that I
found confusing and, as far as I could tell, was not
correct anyway.

Bug: 34851364
Test: Docs changes only. Relying on TreeHugger.
Change-Id: Ie5c6efd6e32ce1e33f8cc45c795cda7d7b2e6583
---
 .../accessibility/AccessibilityEvent.java     | 21 +++++++------------
 1 file changed, 8 insertions(+), 13 deletions(-)

diff --git a/core/java/android/view/accessibility/AccessibilityEvent.java b/core/java/android/view/accessibility/AccessibilityEvent.java
index 79c81b2a2f184..249fd91ee3f9f 100644
--- a/core/java/android/view/accessibility/AccessibilityEvent.java
+++ b/core/java/android/view/accessibility/AccessibilityEvent.java
@@ -365,8 +365,9 @@ import java.util.List;
  * <b>NOTIFICATION TYPES</b></br>
  * </p>
  * <p>
- * <b>Notification state changed</b> - represents the event showing
- * {@link android.app.Notification}.</br>
+ * <b>Notification state changed</b> - represents the event showing a transient piece of information
+ * to the user. This information may be a {@link android.app.Notification} or
+ * {@link android.widget.Toast}.</br>
  * <em>Type:</em> {@link #TYPE_NOTIFICATION_STATE_CHANGED}</br>
  * <em>Properties:</em></br>
  * <ul>
@@ -374,18 +375,12 @@ import java.util.List;
  *   <li>{@link #getClassName()} - The class name of the source.</li>
  *   <li>{@link #getPackageName()} - The package name of the source.</li>
  *   <li>{@link #getEventTime()}  - The event time.</li>
- *   <li>{@link #getParcelableData()} - The posted {@link android.app.Notification}.</li>
- *   <li>{@link #getText()} - Text for providing more context.</li>
+ *   <li>{@link #getParcelableData()} - The posted {@link android.app.Notification}, if
+ *   applicable.</li>
+ *   <li>{@link #getText()} - Displayed text of the {@link android.widget.Toast}, if applicable,
+ *   or may contain text from the {@link android.app.Notification}, although
+ *   {@link #getParcelableData()} is a richer set of data for {@link android.app.Notification}.</li>
  * </ul>
- * <em>Note:</em> This event type is not dispatched to descendants though
- * {@link android.view.View#dispatchPopulateAccessibilityEvent(AccessibilityEvent)
- * View.dispatchPopulateAccessibilityEvent(AccessibilityEvent)}, hence the event
- * source {@link android.view.View} and the sub-tree rooted at it will not receive
- * calls to {@link android.view.View#onPopulateAccessibilityEvent(AccessibilityEvent)
- * View.onPopulateAccessibilityEvent(AccessibilityEvent)}. The preferred way to add
- * text content to such events is by setting the
- * {@link android.R.styleable#View_contentDescription contentDescription} of the source
- * view.</br>
  * </p>
  * <p>
  * <b>EXPLORATION TYPES</b></br>