docs: a couple notes for a11y methods in View and cleanup to the
A11y service HTML to be semantically correct and thus improve its accessibility :)
Change-Id: I483a8a441d802b056f68f82e0e782d86a73298ac
diff --git a/core/java/android/view/View.java b/core/java/android/view/View.java
index 86be28a..a1847b4 100644
--- a/core/java/android/view/View.java
+++ b/core/java/android/view/View.java
@@ -3810,7 +3810,10 @@
* responsible for handling this call.
* </p>
*
- * @param eventType The type of the event to send.
+ * @param eventType The type of the event to send, as defined by several types from
+ * {@link android.view.accessibility.AccessibilityEvent}, such as
+ * {@link android.view.accessibility.AccessibilityEvent#TYPE_VIEW_CLICKED} or
+ * {@link android.view.accessibility.AccessibilityEvent#TYPE_VIEW_HOVER_ENTER}.
*
* @see #onInitializeAccessibilityEvent(AccessibilityEvent)
* @see #dispatchPopulateAccessibilityEvent(AccessibilityEvent)
@@ -3923,27 +3926,28 @@
/**
* Called from {@link #dispatchPopulateAccessibilityEvent(AccessibilityEvent)}
* giving a chance to this View to populate the accessibility event with its
- * text content. While the implementation is free to modify other event
- * attributes this should be performed in
+ * text content. While this method is free to modify event
+ * attributes other than text content, doing so should normally be performed in
* {@link #onInitializeAccessibilityEvent(AccessibilityEvent)}.
* <p>
* Example: Adding formatted date string to an accessibility event in addition
- * to the text added by the super implementation.
- * </p><p><pre><code>
- * public void onPopulateAccessibilityEvent(AccessibilityEvent event) {
+ * to the text added by the super implementation:
+ * <pre> public void onPopulateAccessibilityEvent(AccessibilityEvent event) {
* super.onPopulateAccessibilityEvent(event);
* final int flags = DateUtils.FORMAT_SHOW_DATE | DateUtils.FORMAT_SHOW_WEEKDAY;
* String selectedDateUtterance = DateUtils.formatDateTime(mContext,
* mCurrentDate.getTimeInMillis(), flags);
* event.getText().add(selectedDateUtterance);
- * }
- * </code></pre></p>
+ * }</pre>
* <p>
* If an {@link AccessibilityDelegate} has been specified via calling
* {@link #setAccessibilityDelegate(AccessibilityDelegate)} its
* {@link AccessibilityDelegate#onPopulateAccessibilityEvent(View, AccessibilityEvent)}
* is responsible for handling this call.
* </p>
+ * <p class="note"><strong>Note:</strong> Always call the super implementation before adding
+ * information to the event, in case the default implementation has basic information to add.
+ * </p>
*
* @param event The accessibility event which to populate.
*
@@ -3974,20 +3978,20 @@
* the event.
* <p>
* Example: Setting the password property of an event in addition
- * to properties set by the super implementation.
- * </p><p><pre><code>
- * public void onInitializeAccessibilityEvent(AccessibilityEvent event) {
- * super.onInitializeAccessibilityEvent(event);
- * event.setPassword(true);
- * }
- * </code></pre></p>
+ * to properties set by the super implementation:
+ * <pre> public void onInitializeAccessibilityEvent(AccessibilityEvent event) {
+ * super.onInitializeAccessibilityEvent(event);
+ * event.setPassword(true);
+ * }</pre>
* <p>
* If an {@link AccessibilityDelegate} has been specified via calling
* {@link #setAccessibilityDelegate(AccessibilityDelegate)} its
* {@link AccessibilityDelegate#onInitializeAccessibilityEvent(View, AccessibilityEvent)}
* is responsible for handling this call.
* </p>
- *
+ * <p class="note"><strong>Note:</strong> Always call the super implementation before adding
+ * information to the event, in case the default implementation has basic information to add.
+ * </p>
* @param event The event to initialize.
*
* @see #sendAccessibilityEvent(int)
@@ -6159,8 +6163,7 @@
* are delivered to the view under the pointer. All other generic motion events are
* delivered to the focused view.
* </p>
- * <code>
- * public boolean onGenericMotionEvent(MotionEvent event) {
+ * <pre> public boolean onGenericMotionEvent(MotionEvent event) {
* if ((event.getSource() & InputDevice.SOURCE_CLASS_JOYSTICK) != 0) {
* if (event.getAction() == MotionEvent.ACTION_MOVE) {
* // process the joystick movement...
@@ -6178,8 +6181,7 @@
* }
* }
* return super.onGenericMotionEvent(event);
- * }
- * </code>
+ * }</pre>
*
* @param event The generic motion event being processed.
* @return True if the event was handled, false otherwise.