am 7cf09983: am 27862e05: Merge "docs: Edited Javadoc comments in uiautomator library source files (MR2)." into jb-mr2-dev

* commit '7cf0998379b3c65410d932b7ab061f5fb92c7f2f':
  docs: Edited Javadoc comments in uiautomator library source files (MR2).

5 files changed, 418 insertions, 349 deletions

diff --git a/library/core-src/com/android/uiautomator/core/Configurator.java b/library/core-src/com/android/uiautomator/core/Configurator.java
index 55ed3e7..5f62fc3 100644
--- a/library/core-src/com/android/uiautomator/core/Configurator.java
+++ b/library/core-src/com/android/uiautomator/core/Configurator.java
@@ -16,10 +16,14 @@
 package com.android.uiautomator.core;
 
 /**
- * The Configurator allows for modification of some key framework parameters.
- * New settings take effect immediately and can be changed any time during a test run.
+ * Allows you to set key parameters for running uiautomator tests. The new
+ * settings take effect immediately and can be changed any time during a test run.
  *
- * Can be obtained by calling {@link #getInstance()}
+ * To modify parameters using Configurator, first obtain an instance by calling
+ * {@link #getInstance()}. As a best practice, make sure you always save
+ * the original value of any parameter that you are modifying. After running your
+ * tests with the modified parameters, make sure to also restore
+ * the original parameter values, otherwise this will impact other tests cases.
  * @since API Level 18
  */
 public final class Configurator {
@@ -42,7 +46,7 @@ public final class Configurator {
     }
 
     /**
-     * Retrieves a singleton instance of Configurator
+     * Retrieves a singleton instance of Configurator.
      *
      * @return Configurator instance
      * @since API Level 18
@@ -55,11 +59,15 @@ public final class Configurator {
     }
 
     /**
-     * Sets the timeout used to wait for user interface idle before an automation action.
+     * Sets the timeout for waiting for the user interface to go into an idle
+     * state before starting a uiautomator action.
      *
-     * All automation APIs, except {@link UiDevice}, perform this wait for idle before looking for
-     * the widget specified by the object's {@link UiSelector}. Once idle is detected, a
-     * wait for selector will begin. See {@link #setWaitForSelectorTimeout(long)}
+     * By default, all core uiautomator objects except {@link UiDevice} will perform
+     * this wait before starting to search for the widget specified by the
+     * object's {@link UiSelector}. Once the idle state is detected or the
+     * timeout elapses (whichever occurs first), the object will start to wait
+     * for the selector to find a match.
+     * See {@link #setWaitForSelectorTimeout(long)}
      *
      * @param timeout Timeout value in milliseconds
      * @return self
@@ -71,13 +79,17 @@ public final class Configurator {
     }
 
     /**
-     * Gets the timeout used to wait for user interface idle before an automation action.
+     * Gets the current timeout used for waiting for the user interface to go
+     * into an idle state.
      *
-     * All automation APIs, except {@link UiDevice}, perform this wait for idle before looking for
-     * the widget specified by the object's {@link UiSelector}. Once idle is detected, a
-     * wait for selector will begin. See {@link #setWaitForSelectorTimeout(long)}
+     * By default, all core uiautomator objects except {@link UiDevice} will perform
+     * this wait before starting to search for the widget specified by the
+     * object's {@link UiSelector}. Once the idle state is detected or the
+     * timeout elapses (whichever occurs first), the object will start to wait
+     * for the selector to find a match.
+     * See {@link #setWaitForSelectorTimeout(long)}
      *
-     * @return current timeout in milliseconds
+     * @return Current timeout value in milliseconds
      * @since API Level 18
      */
     public long getWaitForIdleTimeout() {
@@ -85,12 +97,13 @@ public final class Configurator {
     }
 
     /**
-     * Sets the timeout used to wait for a widget matching a selector to become visible
-     * in user interface.
+     * Sets the timeout for waiting for a widget to become visible in the user
+     * interface so that it can be matched by a selector.
      *
-     * The user interface content is dynamic and sometimes the specific widget to be
-     * automated may not yet be visible. This wait allows the framework to keep looking
-     * for a matching widget to the object's {@link UiSelector}, up until the timeout.
+     * Because user interface content is dynamic, sometimes a widget may not
+     * be visible immediately and won't be detected by a selector. This timeout
+     * allows the uiautomator framework to wait for a match to be found, up until
+     * the timeout elapses.
      *
      * @param timeout Timeout value in milliseconds.
      * @return self
@@ -102,14 +115,15 @@ public final class Configurator {
     }
 
     /**
-     * Gets the timeout used to wait for a widget matching a selector to become visible
-     * in user interface.
+     * Gets the current timeout for waiting for a widget to become visible in
+     * the user interface so that it can be matched by a selector.
      *
-     * The user interface content is dynamic and sometimes the specific widget to be
-     * automated, may not yet be visible. This wait allows the framework to keep looking
-     * for a matching widget to the object's {@link UiSelector}, up until the timeout.
+     * Because user interface content is dynamic, sometimes a widget may not
+     * be visible immediately and won't be detected by a selector. This timeout
+     * allows the uiautomator framework to wait for a match to be found, up until
+     * the timeout elapses.
      *
-     * @return current timeout in milliseconds
+     * @return Current timeout value in milliseconds
      * @since API Level 18
      */
     public long getWaitForSelectorTimeout() {
@@ -117,13 +131,13 @@ public final class Configurator {
     }
 
     /**
-     * Sets the timeout used to wait for acknowledgment events caused by automation scroll
-     * swipe action.
+     * Sets the timeout for waiting for an acknowledgement of an
+     * uiautomtor scroll swipe action.
      *
-     * The acknowledgment event is an accessibility event, corresponding to the scroll action.
-     * This acknowledgment helps the framework determine if the requested action was successful.
-     * Changing this timeout value should only be made in very rare cases and in general use,
-     * should not be modified.
+     * The acknowledgment is an <a href="http://developer.android.com/reference/android/view/accessibility/AccessibilityEvent.html">AccessibilityEvent</a>,
+     * corresponding to the scroll action, that lets the framework determine if
+     * the scroll action was successful. Generally, this timeout should not be modified.
+     * See {@link UiScrollable}
      *
      * @param timeout Timeout value in milliseconds
      * @return self
@@ -135,13 +149,13 @@ public final class Configurator {
     }
 
     /**
-     * Gets the timeout used to wait for acknowledgment events caused by automation scroll
-     * swipe action.
+     * Gets the timeout for waiting for an acknowledgement of an
+     * uiautomtor scroll swipe action.
      *
-     * The acknowledgment event is an accessibility event, corresponding to the scroll action.
-     * This acknowledgment helps the framework determine if the requested action was successful.
-     * Changing this timeout value should only be made in very rare cases and in general use,
-     * should not be modified.
+     * The acknowledgment is an <a href="http://developer.android.com/reference/android/view/accessibility/AccessibilityEvent.html">AccessibilityEvent</a>,
+     * corresponding to the scroll action, that lets the framework determine if
+     * the scroll action was successful. Generally, this timeout should not be modified.
+     * See {@link UiScrollable}
      *
      * @return current timeout in milliseconds
      * @since API Level 18
@@ -151,13 +165,13 @@ public final class Configurator {
     }
 
     /**
-     * Sets the timeout used to wait for acknowledgment events caused by generic automation
-     * actions such as clicks, setText, pressMenu etc...
+     * Sets the timeout for waiting for an acknowledgment of generic uiautomator
+     * actions, such as clicks, text setting, and menu presses.
      *
-     * The acknowledgment event is an accessibility event, corresponding to an action, that the
-     * framework looks for after an action is performed. This acknowledgment helps the
-     * framework determine if the requested action was successful. Changing this timeout
-     * value should only be made in very rare cases and in general use, should not be modified.
+     * The acknowledgment is an <a href="http://developer.android.com/reference/android/view/accessibility/AccessibilityEvent.html">AccessibilityEvent</a>,
+     * corresponding to an action, that lets the framework determine if the
+     * action was successful. Generally, this timeout should not be modified.
+     * See {@link UiObject}
      *
      * @param timeout Timeout value in milliseconds
      * @return self
@@ -169,13 +183,13 @@ public final class Configurator {
     }
 
     /**
-     * Gets the timeout used to wait for acknowledgment events caused by generic automation
-     * actions such as clicks, setText, pressMenu etc...
+     * Gets the current timeout for waiting for an acknowledgment of generic
+     * uiautomator actions, such as clicks, text setting, and menu presses.
      *
-     * The acknowledgment event is an accessibility event, corresponding to an action, that the
-     * framework looks for after an action is performed. This acknowledgment helps the
-     * framework determine if the requested action was successful. Changing this timeout
-     * value should only be made in very rare cases and in general use, should not be modified.
+     * The acknowledgment is an <a href="http://developer.android.com/reference/android/view/accessibility/AccessibilityEvent.html">AccessibilityEvent</a>,
+     * corresponding to an action, that lets the framework determine if the
+     * action was successful. Generally, this timeout should not be modified.
+     * See {@link UiObject}
      *
      * @return current timeout in milliseconds
      * @since API Level 18
@@ -185,7 +199,8 @@ public final class Configurator {
     }
 
     /**
-     * Sets a delay between key presses when sending text.
+     * Sets a delay between key presses when injecting text input.
+     * See {@link UiObject#setText(String)}
      *
      * @param delay Delay value in milliseconds
      * @return self
@@ -197,7 +212,8 @@ public final class Configurator {
     }
 
     /**
-     * Gets the delay between key presses when sending text.
+     * Gets the current delay between key presses when injecting text input.
+     * See {@link UiObject#setText(String)}
      *
      * @return current delay in milliseconds
      * @since API Level 18
@@ -205,4 +221,4 @@ public final class Configurator {
     public long getKeyInjectionDelay() {
         return mKeyInjectionDelay;
     }
-}
+
diff --git a/library/core-src/com/android/uiautomator/core/UiDevice.java b/library/core-src/com/android/uiautomator/core/UiDevice.java
index fc23cdf..9b69d62 100644
--- a/library/core-src/com/android/uiautomator/core/UiDevice.java
+++ b/library/core-src/com/android/uiautomator/core/UiDevice.java
@@ -90,13 +90,14 @@ public class UiDevice {
     }
 
     /**
-     * Enabled or disabled the compressed layout hierarchy
+     * Enables or disables layout hierarchy compression.
      *
-     * Enabling the compressed layout hierarchy, limits the layout hierarchy returned
-     * by accessibility, only to the important nodes to automation, removing unnecessary
-     * surrounding layout nodes that make viewing and searching the hierarchy inefficient.
+     * If compression is enabled, the layout hierarchy derived from the Acessibility
+     * framework will only contain nodes that are important for uiautomator
+     * testing. Any unnecessary surrounding layout nodes that make viewing
+     * and searching the hierarchy inefficient are removed.
      *
-     * @param compressed is true to enabled else false to disable
+     * @param compressed true to enable compression; else, false to disable
      * @since API Level 18
      */
     public void setCompressedLayoutHeirarchy(boolean compressed) {
@@ -343,7 +344,7 @@ public class UiDevice {
     }
 
     /**
-     * Opens the notification shade
+     * Opens the notification shade.
      *
      * @return true if successful, else return false
      * @since API Level 18
@@ -355,7 +356,7 @@ public class UiDevice {
     }
 
     /**
-     * Opens the quick settings shade
+     * Opens the Quick Settings shade.
      *
      * @return true if successful, else return false
      * @since API Level 18
@@ -430,16 +431,18 @@ public class UiDevice {
     }
 
     /**
-     * Performs a swipe from one coordinate to another using the number of steps
-     * to determine smoothness and speed. Each step execution is throttled to 5ms
-     * per step. So for a 100 steps, the swipe will take about 1/2 second to complete.
+     * Performs a swipe from one coordinate to another coordinate. You can control
+     * the smoothness and speed of the swipe by specifying the number of steps.
+     * Each step execution is throttled to 5 milliseconds per step, so for a 100
+     * steps, the swipe will take around 0.5 seconds to complete.
      *
-     * @param startX
-     * @param startY
-     * @param endX
-     * @param endY
-     * @param steps is the number of move steps sent to the system
-     * @return false if the operation fails or the coordinates are invalid
+     * @param startX X-axis value for the starting coordinate
+     * @param startY Y-axis value for the starting coordinate
+     * @param endX X-axis value for the ending coordinate
+     * @param endY Y-axis value for the ending coordinate
+     * @param steps is the number of steps for the swipe action
+     * @return true if swipe is performed, false if the operation fails 
+     * or the coordinates are invalid
      * @since API Level 18
      */
     public boolean drag(int startX, int startY, int endX, int endY, int steps) {
@@ -845,4 +848,4 @@ public class UiDevice {
         Tracer.trace(storePath, scale, quality);
         return getAutomatorBridge().takeScreenshot(storePath, quality);
     }
-}
+
diff --git a/library/core-src/com/android/uiautomator/core/UiObject.java b/library/core-src/com/android/uiautomator/core/UiObject.java
index 4862ca5..d9ba745 100644
--- a/library/core-src/com/android/uiautomator/core/UiObject.java
+++ b/library/core-src/com/android/uiautomator/core/UiObject.java
@@ -25,11 +25,11 @@ import android.view.MotionEvent.PointerCoords;
 import android.view.accessibility.AccessibilityNodeInfo;
 
 /**
- * A UiObject is a representation of a UI element. It is not in any way directly bound to a
- * UI element as an object reference. A UiObject holds information to help it
- * locate a matching UI element at runtime based on the {@link UiSelector} properties specified in
- * its constructor. Since a UiObject is a representative for a UI element, it can
- * be reused for different views with matching UI elements.
+ * A UiObject is a representation of a view. It is not in any way directly bound to a
+ * view as an object reference. A UiObject contains information to help it
+ * locate a matching view at runtime based on the {@link UiSelector} properties specified in
+ * its constructor. Once you create an instance of a UiObject, it can
+ * be reused for different views that match the selector criteria.
  * @since API Level 16
  */
 public class UiObject {
@@ -69,8 +69,8 @@ public class UiObject {
     private final Configurator mConfig = Configurator.getInstance();
 
     /**
-     * Constructs a UiObject to represent a specific UI element matched by the specified
-     * {@link UiSelector} selector properties.
+     * Constructs a UiObject to represent a view that matches the specified
+     * selector criteria.
      * @param selector
      * @since API Level 16
      */
@@ -102,7 +102,7 @@ public class UiObject {
 
     /**
      * Retrieves the {@link InteractionController} to perform finger actions such as tapping,
-     * swiping or entering text.
+     * swiping, or entering text.
      *
      * @return {@link InteractionController}
      */
@@ -111,11 +111,10 @@ public class UiObject {
     }
 
     /**
-     * Creates a new UiObject representing a child UI element of the element currently represented
-     * by this UiObject.
+     * Creates a new UiObject for a child view that is under the present UiObject.
      *
-     * @param selector for UI element to match
-     * @return a new UiObject representing the matched UI element
+     * @param selector for child view to match
+     * @return a new UiObject representing the child view
      * @since API Level 16
      */
     public UiObject getChild(UiSelector selector) throws UiObjectNotFoundException {
@@ -124,13 +123,11 @@ public class UiObject {
     }
 
     /**
-     * Creates a new UiObject representing a child UI element from the parent element currently
-     * represented by this object. Essentially this is starting the search from the parent
-     * element and can also be used to find sibling UI elements to the one currently represented
-     * by this UiObject.
+     * Creates a new UiObject for a sibling view or a child of the sibling view, 
+     * relative to the present UiObject.
      *
-     * @param selector for the UI element to match
-     * @return a new UiObject representing the matched UI element
+     * @param selector for a sibling view or children of the sibling view
+     * @return a new UiObject representing the matched view
      * @throws UiObjectNotFoundException
      * @since API Level 16
      */
@@ -140,10 +137,9 @@ public class UiObject {
     }
 
     /**
-     * Counts the child UI elements immediately under the UI element currently represented by
-     * this UiObject.
+     * Counts the child views immediately under the present UiObject.
      *
-     * @return the count of child UI elements.
+     * @return the count of child views.
      * @throws UiObjectNotFoundException
      * @since API Level 16
      */
@@ -157,8 +153,8 @@ public class UiObject {
     }
 
     /**
-     * Uses the member UiSelector properties to find a matching UI element reported in
-     * the accessibility hierarchy.
+     * Finds a matching UI element in the accessibility hierarchy, by
+     * using the selector for this UiObject.
      *
      * @param timeout in milliseconds
      * @return AccessibilityNodeInfo if found else null
@@ -185,13 +181,14 @@ public class UiObject {
     }
 
     /**
-     * Performs a drag of this object to a destination UiObject. Note that the number of steps
-     * used can influence the drag speed and varying speeds may impact the results. Consider
-     * evaluating different speeds when testing this method.
+     * Drags this object to a destination UiObject.
+     * The number of steps specified in your input parameter can influence the
+     * drag speed, and varying speeds may impact the results. Consider
+     * evaluating different speeds when using this method in your tests.
      *
-     * @param destObj
-     * @param steps usually 40 steps. More or less to change the speed.
-     * @return true of successful
+     * @param destObj the destination UiObject.
+     * @param steps usually 40 steps. You can increase or decrease the steps to change the speed.
+     * @return true if successful
      * @throws UiObjectNotFoundException
      * @since API Level 18
      */
@@ -203,14 +200,15 @@ public class UiObject {
     }
 
     /**
-     * Performs a drag of this object to arbitrary coordinates. Note that the number of steps
-     * used will influence the drag speed and varying speeds may impact the results. Consider
-     * evaluating different speeds when testing this method.
+     * Drags this object to arbitrary coordinates.
+     * The number of steps specified in your input parameter can influence the
+     * drag speed, and varying speeds may impact the results. Consider
+     * evaluating different speeds when using this method in your tests.
      *
-     * @param destX
-     * @param destY
-     * @param steps
-     * @return true of successful
+     * @param destX the X-axis coordinate.
+     * @param destY the Y-axis coordinate.
+     * @param steps usually 40 steps. You can increase or decrease the steps to change the speed.
+     * @return true if successful
      * @throws UiObjectNotFoundException
      * @since API Level 18
      */
@@ -221,9 +219,14 @@ public class UiObject {
     }
 
     /**
-     * Perform the action on the UI element that is represented by this UiObject. Also see
-     * {@link UiScrollable#scrollToBeginning(int)}, {@link UiScrollable#scrollToEnd(int)},
-     * {@link UiScrollable#scrollBackward()}, {@link UiScrollable#scrollForward()}.
+     * Performs the swipe up action on the UiObject. 
+     * See also:
+     * <ul>
+     * <li>{@link UiScrollable#scrollToBeginning(int)}</li>
+     * <li>{@link UiScrollable#scrollToEnd(int)}</li>
+     * <li>{@link UiScrollable#scrollBackward()}</li>
+     * <li>{@link UiScrollable#scrollForward()}</li>
+     * </ul>
      *
      * @param steps indicates the number of injected move steps into the system. Steps are
      * injected about 5ms apart. So a 100 steps may take about 1/2 second to complete.
@@ -242,12 +245,16 @@ public class UiObject {
     }
 
     /**
-     * Perform the action on the UI element that is represented by this object, Also see
-     * {@link UiScrollable#scrollToBeginning(int)}, {@link UiScrollable#scrollToEnd(int)},
-     * {@link UiScrollable#scrollBackward()}, {@link UiScrollable#scrollForward()}. This method will
-     * perform the swipe gesture over any surface.  The targeted UI element does not need to have
-     * the attribute <code>scrollable</code> set to <code>true</code> for this operation to be
-     * performed.
+     * Performs the swipe down action on the UiObject. 
+     * The swipe gesture can be performed over any surface. The targeted
+     * UI element does not need to be scrollable.
+     * See also:
+     * <ul>
+     * <li>{@link UiScrollable#scrollToBeginning(int)}</li>
+     * <li>{@link UiScrollable#scrollToEnd(int)}</li>
+     * <li>{@link UiScrollable#scrollBackward()}</li>
+     * <li>{@link UiScrollable#scrollForward()}</li>
+     * </ul>
      *
      * @param steps indicates the number of injected move steps into the system. Steps are
      * injected about 5ms apart. So a 100 steps may take about 1/2 second to complete.
@@ -266,12 +273,16 @@ public class UiObject {
     }
 
     /**
-     * Perform the action on the UI element that is represented by this object. Also see
-     * {@link UiScrollable#scrollToBeginning(int)}, {@link UiScrollable#scrollToEnd(int)},
-     * {@link UiScrollable#scrollBackward()}, {@link UiScrollable#scrollForward()}. This method will
-     * perform the swipe gesture over any surface. The targeted UI element does not need to have the
-     * attribute <code>scrollable</code> set to <code>true</code> for this operation to be
-     * performed.
+     * Performs the swipe left action on the UiObject. 
+     * The swipe gesture can be performed over any surface. The targeted
+     * UI element does not need to be scrollable.
+     * See also:
+     * <ul>
+     * <li>{@link UiScrollable#scrollToBeginning(int)}</li>
+     * <li>{@link UiScrollable#scrollToEnd(int)}</li>
+     * <li>{@link UiScrollable#scrollBackward()}</li>
+     * <li>{@link UiScrollable#scrollForward()}</li>
+     * </ul>
      *
      * @param steps indicates the number of injected move steps into the system. Steps are
      * injected about 5ms apart. So a 100 steps may take about 1/2 second to complete.
@@ -289,12 +300,16 @@ public class UiObject {
     }
 
     /**
-     * Perform the action on the UI element that is represented by this object. Also see
-     * {@link UiScrollable#scrollToBeginning(int)}, {@link UiScrollable#scrollToEnd(int)},
-     * {@link UiScrollable#scrollBackward()}, {@link UiScrollable#scrollForward()}. This method will
-     * perform the swipe gesture over any surface. The targeted UI element does not need to have the
-     * attribute <code>scrollable</code> set to <code>true</code> for this operation to be
-     * performed.
+     * Performs the swipe right action on the UiObject. 
+     * The swipe gesture can be performed over any surface. The targeted
+     * UI element does not need to be scrollable.
+     * See also:
+     * <ul>
+     * <li>{@link UiScrollable#scrollToBeginning(int)}</li>
+     * <li>{@link UiScrollable#scrollToEnd(int)}</li>
+     * <li>{@link UiScrollable#scrollBackward()}</li>
+     * <li>{@link UiScrollable#scrollForward()}</li>
+     * </ul>
      *
      * @param steps indicates the number of injected move steps into the system. Steps are
      * injected about 5ms apart. So a 100 steps may take about 1/2 second to complete.
@@ -343,10 +358,10 @@ public class UiObject {
     }
 
     /**
-     * Walk the hierarchy up to find a scrollable parent. A scrollable parent
-     * indicates that this node may be in a content where it is partially
-     * visible due to scrolling. its clickable center maybe invisible and
-     * adjustments should be made to the click coordinates.
+     * Walks up the layout hierarchy to find a scrollable parent. A scrollable parent
+     * indicates that this node might be in a container where it is partially
+     * visible due to scrolling. In this case, its clickable center might not be visible and
+     * the click coordinates should be adjusted.
      *
      * @param node
      * @return The accessibility node info.
@@ -382,9 +397,9 @@ public class UiObject {
     }
 
     /**
+     * Waits for window transitions that would typically take longer than the
+     * usual default timeouts.
      * See {@link #clickAndWaitForNewWindow(long)}
-     * This method is intended to reliably wait for window transitions that would typically take
-     * longer than the usual default timeouts.
      *
      * @return true if the event was triggered, else false
      * @throws UiObjectNotFoundException
@@ -525,10 +540,10 @@ public class UiObject {
     }
 
     /**
-     * Reads the <code>className</code> property of the UI element
+     * Retrieves the <code>className</code> property of the UI element.
      *
      * @return class name of the current node represented by this UiObject
-     * @throws UiObjectNotFoundException if no match could be found
+     * @throws UiObjectNotFoundException if no match was found
      * @since API Level 18
      */
     public String getClassName() throws UiObjectNotFoundException {
@@ -635,7 +650,7 @@ public class UiObject {
     }
 
     /**
-     * Check if the UI element's <code>selected</code> property is currently true
+     * Checks if the UI element's <code>selected</code> property is currently true.
      *
      * @return true if it is else false
      * @throws UiObjectNotFoundException
@@ -651,7 +666,7 @@ public class UiObject {
     }
 
     /**
-     * Check if the UI element's <code>checkable</code> property is currently true
+     * Checks if the UI element's <code>checkable</code> property is currently true.
      *
      * @return true if it is else false
      * @throws UiObjectNotFoundException
@@ -667,7 +682,7 @@ public class UiObject {
     }
 
     /**
-     * Check if the UI element's <code>enabled</code> property is currently true
+     * Checks if the UI element's <code>enabled</code> property is currently true.
      *
      * @return true if it is else false
      * @throws UiObjectNotFoundException
@@ -683,7 +698,7 @@ public class UiObject {
     }
 
     /**
-     * Check if the UI element's <code>clickable</code> property is currently true
+     * Checks if the UI element's <code>clickable</code> property is currently true.
      *
      * @return true if it is else false
      * @throws UiObjectNotFoundException
@@ -715,7 +730,7 @@ public class UiObject {
     }
 
     /**
-     * Check if the UI element's <code>focusable</code> property is currently true
+     * Check if the UI element's <code>focusable</code> property is currently true.
      *
      * @return true if it is else false
      * @throws UiObjectNotFoundException
@@ -731,7 +746,7 @@ public class UiObject {
     }
 
     /**
-     * Check if the UI element's <code>scrollable</code> property is currently true
+     * Check if the view's <code>scrollable</code> property is currently true
      *
      * @return true if it is else false
      * @throws UiObjectNotFoundException
@@ -747,7 +762,7 @@ public class UiObject {
     }
 
     /**
-     * Check if the UI element's <code>long-clickable</code> property is currently true
+     * Check if the view's <code>long-clickable</code> property is currently true
      *
      * @return true if it is else false
      * @throws UiObjectNotFoundException
@@ -763,7 +778,7 @@ public class UiObject {
     }
 
     /**
-     * Reads the UI element's <code>package</code> property
+     * Reads the view's <code>package</code> property
      *
      * @return true if it is else false
      * @throws UiObjectNotFoundException
@@ -779,9 +794,9 @@ public class UiObject {
     }
 
     /**
-     * Returns the visible bounds of the UI element.
+     * Returns the visible bounds of the view.
      *
-     * If a portion of the UI element is visible, only the bounds of the visible portion are
+     * If a portion of the view is visible, only the bounds of the visible portion are
      * reported.
      *
      * @return Rect
@@ -799,7 +814,7 @@ public class UiObject {
     }
 
     /**
-     * Returns the UI element's <code>bounds</code> property. See {@link #getVisibleBounds()}
+     * Returns the view's <code>bounds</code> property. See {@link #getVisibleBounds()}
      *
      * @return Rect
      * @throws UiObjectNotFoundException
@@ -818,14 +833,14 @@ public class UiObject {
     }
 
     /**
-     * Waits a specified length of time for a UI element to become visible.
+     * Waits a specified length of time for a view to become visible.
      *
-     * This method waits until the UI element becomes visible on the display, or
+     * This method waits until the view becomes visible on the display, or
      * until the timeout has elapsed. You can use this method in situations where
      * the content that you want to select is not immediately displayed.
      *
      * @param timeout the amount of time to wait (in milliseconds)
-     * @return true if the UI element is displayed, else false if timeout elapsed while waiting
+     * @return true if the view is displayed, else false if timeout elapsed while waiting
      * @since API Level 16
      */
     public boolean waitForExists(long timeout) {
@@ -837,12 +852,12 @@ public class UiObject {
     }
 
     /**
-     * Waits a specified length of time for a UI element to become undetectable.
+     * Waits a specified length of time for a view to become undetectable.
      *
-     * This method waits until a UI element is no longer matchable, or until the
+     * This method waits until a view is no longer matchable, or until the
      * timeout has elapsed.
      *
-     * A UI element becomes undetectable when the {@link UiSelector} of the object is
+     * A view becomes undetectable when the {@link UiSelector} of the object is
      * unable to find a match because the element has either changed its state or is no
      * longer displayed.
      *
@@ -869,14 +884,14 @@ public class UiObject {
     }
 
     /**
-     * Check if UI element exists.
+     * Check if view exists.
      *
      * This methods performs a {@link #waitForExists(long)} with zero timeout. This
-     * basically returns immediately whether the UI element represented by this UiObject
-     * exists or not. If you need to wait longer for this UI element, then see
+     * basically returns immediately whether the view represented by this UiObject
+     * exists or not. If you need to wait longer for this view, then see
      * {@link #waitForExists(long)}.
      *
-     * @return true if the UI element represented by this UiObject does exist
+     * @return true if the view represented by this UiObject does exist
      * @since API Level 16
      */
     public boolean exists() {
@@ -891,14 +906,14 @@ public class UiObject {
     }
 
     /**
-     * PinchOut generates a 2 pointer gesture where each pointer is moving from the center out
-     * away from each other diagonally towards the edges of the current UI element represented by
+     * Performs a two-pointer gesture, where each pointer moves diagonally
+     * opposite across the other, from the center out towards the edges of the
      * this UiObject.
-     * @param percent of the object's diagonal length to use for the pinch
-     * @param steps indicates the number of injected move steps into the system. Steps are
-     * injected about 5ms apart. So a 100 steps may take about 1/2 second to complete.
+     * @param percent percentage of the object's diagonal length for the pinch gesture
+     * @param steps the number of steps for the gesture. Steps are injected 
+     * about 5 milliseconds apart, so 100 steps may take around 0.5 seconds to complete.
      * @return <code>true</code> if all touch events for this gesture are injected successfully,
-     *          <code>false</code> otherwise
+     *         <code>false</code> otherwise
      * @throws UiObjectNotFoundException
      * @since API Level 18
      */
@@ -930,14 +945,13 @@ public class UiObject {
     }
 
     /**
-     * PinchIn generates a 2 pointer gesture where each pointer is moving towards the other
-     * diagonally from the edges of the current UI element represented by this UiObject, until the
-     * center.
-     * @param percent of the object's diagonal length to use for the pinch
-     * @param steps indicates the number of injected move steps into the system. Steps are
-     * injected about 5ms apart. So a 100 steps may take about 1/2 second to complete.
+     * Performs a two-pointer gesture, where each pointer moves diagonally
+     * toward the other, from the edges to the center of this UiObject .
+     * @param percent percentage of the object's diagonal length for the pinch gesture
+     * @param steps the number of steps for the gesture. Steps are injected 
+     * about 5 milliseconds apart, so 100 steps may take around 0.5 seconds to complete.
      * @return <code>true</code> if all touch events for this gesture are injected successfully,
-     *          <code>false</code> otherwise
+     *         <code>false</code> otherwise
      * @throws UiObjectNotFoundException
      * @since API Level 18
      */
@@ -967,16 +981,16 @@ public class UiObject {
     }
 
     /**
-     * Generates a 2 pointer gesture from an arbitrary starting and ending points.
+     * Generates a two-pointer gesture with arbitrary starting and ending points.
      *
      * @param startPoint1 start point of pointer 1
      * @param startPoint2 start point of pointer 2
      * @param endPoint1 end point of pointer 1
      * @param endPoint2 end point of pointer 2
-     * @param steps indicates the number of injected move steps into the system. Steps are
-     * injected about 5ms apart. So a 100 steps may take about 1/2 second to complete.
+     * @param steps the number of steps for the gesture. Steps are injected 
+     * about 5 milliseconds apart, so 100 steps may take around 0.5 seconds to complete.
      * @return <code>true</code> if all touch events for this gesture are injected successfully,
-     *          <code>false</code> otherwise
+     *         <code>false</code> otherwise
      * @since API Level 18
      */
     public boolean performTwoPointerGesture(Point startPoint1, Point startPoint2, Point endPoint1,
@@ -1042,15 +1056,13 @@ public class UiObject {
     }
 
     /**
-     * Performs a multi-touch gesture
+     * Performs a multi-touch gesture. You must specify touch coordinates for
+     * at least 2 pointers. Each pointer must have all of its touch steps
+     * defined in an array of {@link PointerCoords}. You can use this method to
+     * specify complex gestures, like circles and irregular shapes, where each
+     * pointer may take a different path.
      *
-     * Takes a series of touch coordinates for at least 2 pointers. Each pointer must have
-     * all of its touch steps defined in an array of {@link PointerCoords}. By having the ability
-     * to specify the touch points along the path of a pointer, the caller is able to specify
-     * complex gestures like circles, irregular shapes etc, where each pointer may take a
-     * different path.
-     *
-     * To create a single point on a pointer's touch path
+     * To create a single point on a pointer's touch path:
      * <code>
      *       PointerCoords p = new PointerCoords();
      *       p.x = stepX;
@@ -1058,14 +1070,14 @@ public class UiObject {
      *       p.pressure = 1;
      *       p.size = 1;
      * </code>
-     * @param touches each array of {@link PointerCoords} constitute a single pointer's touch path.
-     *        Multiple {@link PointerCoords} arrays constitute multiple pointers, each with its own
-     *        path. Each {@link PointerCoords} in an array constitute a point on a pointer's path.
+     * @param touches represents the pointers' paths. Each {@link PointerCoords} 
+     * array represents a different pointer. Each {@link PointerCoords} in an 
+     * array element represents a touch point on a pointer's path.
      * @return <code>true</code> if all touch events for this gesture are injected successfully,
-     *          <code>false</code> otherwise
+     *         <code>false</code> otherwise
      * @since API Level 18
      */
     public boolean performMultiPointerGesture(PointerCoords[] ...touches) {
         return getInteractionController().performMultiPointerGesture(touches);
     }
-}
+
diff --git a/library/core-src/com/android/uiautomator/core/UiScrollable.java b/library/core-src/com/android/uiautomator/core/UiScrollable.java
index f5306af..9b14c10 100644
--- a/library/core-src/com/android/uiautomator/core/UiScrollable.java
+++ b/library/core-src/com/android/uiautomator/core/UiScrollable.java
@@ -20,8 +20,9 @@ import android.util.Log;
 import android.view.accessibility.AccessibilityNodeInfo;
 
 /**
- * UiScrollable is a {@link UiCollection} and provides support for searching for items in a
- * scrollable UI elements. Used with horizontally or vertically scrollable UI.
+ * UiScrollable is a {@link UiCollection} and provides support for searching
+ * for items in scrollable layout elements. This class can be used with
+ * horizontally or vertically scrollable controls.
  * @since API Level 16
  */
 public class UiScrollable extends UiCollection {
@@ -44,11 +45,10 @@ public class UiScrollable extends UiCollection {
     private double mSwipeDeadZonePercentage = DEFAULT_SWIPE_DEADZONE_PCT;
 
     /**
-     * UiScrollable is a {@link UiCollection} and as such requires a {@link UiSelector} to
-     * identify the container UI element of the scrollable collection. Further operations on
-     * the items in the container will require specifying UiSelector as an item selector.
+     * Constructor.
      *
-     * @param container a {@link UiSelector} selector
+     * @param container a {@link UiSelector} selector to identify the scrollable
+     *     layout element.
      * @since API Level 16
      */
     public UiScrollable(UiSelector container) {
@@ -58,7 +58,7 @@ public class UiScrollable extends UiCollection {
     }
 
     /**
-     * Set the direction of swipes when performing scroll search
+     * Set the direction of swipes to be vertical when performing scroll actions.
      * @return reference to itself
      * @since API Level 16
      */
@@ -69,7 +69,7 @@ public class UiScrollable extends UiCollection {
     }
 
     /**
-     * Set the direction of swipes when performing scroll search
+     * Set the direction of swipes to be horizontal when performing scroll actions.
      * @return reference to itself
      * @since API Level 16
      */
@@ -95,17 +95,19 @@ public class UiScrollable extends UiCollection {
     }
 
     /**
-     * Searches for child UI element within the constraints of this UiScrollable {@link UiSelector}
-     * container. It looks for any child matching the <code>childPattern</code> argument within its
-     * hierarchy with a matching content-description text. The returned UiObject will represent the
-     * UI element matching the <code>childPattern</code> and not the sub element that matched the
-     * content description.</p>
-     * By default this operation will perform scroll search while attempting to find the UI element
+     * Searches for a child element in the present scrollable container.
+     * The search first looks for a child element that matches the selector
+     * you provided, then looks for the content-description in its children elements.
+     * If both search conditions are fulfilled, the method returns a {@ link UiObject}
+     * representing the element matching the selector (not the child element in its
+     * subhierarchy containing the content-description). By default, this method performs a
+     * scroll search.
      * See {@link #getChildByDescription(UiSelector, String, boolean)}
      *
-     * @param childPattern {@link UiSelector} selector of the child pattern to match and return
-     * @param text String of the identifying child contents of of the <code>childPattern</code>
-     * @return {@link UiObject} pointing at and instance of <code>childPattern</code>
+     * @param childPattern {@link UiSelector} for a child in a scollable layout element
+     * @param text Content-description to find in the children of 
+     * the <code>childPattern</code> match
+     * @return {@link UiObject} representing the child element that matches the search conditions
      * @throws UiObjectNotFoundException
      * @since API Level 16
      */
@@ -117,12 +119,18 @@ public class UiScrollable extends UiCollection {
     }
 
     /**
-     * See {@link #getChildByDescription(UiSelector, String)}
-     *
-     * @param childPattern {@link UiSelector} selector of the child pattern to match and return
-     * @param text String may be a partial match for the content-description of a child element.
+     * Searches for a child element in the present scrollable container.
+     * The search first looks for a child element that matches the selector
+     * you provided, then looks for the content-description in its children elements.
+     * If both search conditions are fulfilled, the method returns a {@ link UiObject}
+     * representing the element matching the selector (not the child element in its
+     * subhierarchy containing the content-description).
+     *
+     * @param childPattern {@link UiSelector} for a child in a scollable layout element
+     * @param text Content-description to find in the children of 
+     * the <code>childPattern</code> match (may be a partial match)
      * @param allowScrollSearch set to true if scrolling is allowed
-     * @return {@link UiObject} pointing at and instance of <code>childPattern</code>
+     * @return {@link UiObject} representing the child element that matches the search conditions
      * @throws UiObjectNotFoundException
      * @since API Level 16
      */
@@ -139,14 +147,14 @@ public class UiScrollable extends UiCollection {
     }
 
     /**
-     * Searches for child UI element within the constraints of this UiScrollable {@link UiSelector}
-     * selector. It looks for any child matching the <code>childPattern</code> argument and
-     * return the <code>instance</code> specified. The operation is performed only on the visible
-     * items and no scrolling is performed in this case.
-     *
-     * @param childPattern {@link UiSelector} selector of the child pattern to match and return
-     * @param instance int the desired matched instance of this <code>childPattern</code>
-     * @return {@link UiObject} pointing at and instance of <code>childPattern</code>
+     * Searches for a child element in the present scrollable container that
+     * matches the selector you provided. The search is performed without
+     * scrolling and only on visible elements.
+     *
+     * @param childPattern {@link UiSelector} for a child in a scollable layout element
+     * @param instance int number representing the occurance of 
+     * a <code>childPattern</code> match
+     * @return {@link UiObject} representing the child element that matches the search conditions
      * @since API Level 16
      */
     @Override
@@ -159,18 +167,18 @@ public class UiScrollable extends UiCollection {
     }
 
     /**
-     * Searches for child UI element within the constraints of this UiScrollable {@link UiSelector}
-     * container. It looks for any child matching the <code>childPattern</code> argument that has
-     * a sub UI element anywhere within its sub hierarchy that has text attribute
-     * <code>text</code>. The returned UiObject will point at the <code>childPattern</code>
-     * instance that matched the search and not at the text matched sub element</p>
-     * By default this operation will perform scroll search while attempting to find the UI
-     * element.
+     * Searches for a child element in the present scrollable
+     * container. The search first looks for a child element that matches the
+     * selector you provided, then looks for the text in its children elements.
+     * If both search conditions are fulfilled, the method returns a {@ link UiObject}
+     * representing the element matching the selector (not the child element in its
+     * subhierarchy containing the text). By default, this method performs a
+     * scroll search.
      * See {@link #getChildByText(UiSelector, String, boolean)}
      *
-     * @param childPattern {@link UiSelector} selector of the child pattern to match and return
-     * @param text String of the identifying child contents of of the <code>childPattern</code>
-     * @return {@link UiObject} pointing at and instance of <code>childPattern</code>
+     * @param childPattern {@link UiSelector} selector for a child in a scrollable layout element
+     * @param text String to find in the children of the <code>childPattern</code> match
+     * @return {@link UiObject} representing the child element that matches the search conditions
      * @throws UiObjectNotFoundException
      * @since API Level 16
      */
@@ -182,12 +190,17 @@ public class UiScrollable extends UiCollection {
     }
 
     /**
-     * See {@link #getChildByText(UiSelector, String)}
-     *
-     * @param childPattern {@link UiSelector} selector of the child pattern to match and return
-     * @param text String of the identifying child contents of of the <code>childPattern</code>
+     * Searches for a child element in the present scrollable container. The
+     * search first looks for a child element that matches the
+     * selector you provided, then looks for the text in its children elements.
+     * If both search conditions are fulfilled, the method returns a {@ link UiObject}
+     * representing the element matching the selector (not the child element in its
+     * subhierarchy containing the text).
+     *
+     * @param childPattern {@link UiSelector} selector for a child in a scrollable layout element
+     * @param text String to find in the children of the <code>childPattern</code> match
      * @param allowScrollSearch set to true if scrolling is allowed
-     * @return {@link UiObject} pointing at and instance of <code>childPattern</code>
+     * @return {@link UiObject} representing the child element that matches the search conditions
      * @throws UiObjectNotFoundException
      * @since API Level 16
      */
@@ -204,11 +217,12 @@ public class UiScrollable extends UiCollection {
     }
 
     /**
-     * Performs a swipe Up on the UI element until the requested content-description
-     * is visible or until swipe attempts have been exhausted. See {@link #setMaxSearchSwipes(int)}
+     * Performs a forward scroll action on the scrollable layout element until
+     * the content-description is found, or until swipe attempts have been exhausted.
+     * See {@link #setMaxSearchSwipes(int)}
      *
-     * @param text to look for anywhere within the contents of this scrollable.
-     * @return true if item us found else false
+     * @param text content-description to find within the contents of this scrollable layout element.
+     * @return true if item is found; else, false
      * @since API Level 16
      */
     public boolean scrollDescriptionIntoView(String text) throws UiObjectNotFoundException {
@@ -217,8 +231,8 @@ public class UiScrollable extends UiCollection {
     }
 
     /**
-     * Perform a scroll search for a UI element matching the {@link UiSelector} selector argument.
-     * See {@link #scrollDescriptionIntoView(String)} and {@link #scrollTextIntoView(String)}.
+     * Perform a forward scroll action to move through the scrollable layout element until
+     * a visible item that matches the {@link UiObject} is found.
      *
      * @param obj {@link UiObject}
      * @return true if the item was found and now is in view else false
@@ -230,11 +244,13 @@ public class UiScrollable extends UiCollection {
     }
 
     /**
-     * Perform a scroll search for a UI element matching the {@link UiSelector} selector argument.
+     * Perform a scroll forward action to move through the scrollable layout 
+     * element until a visible item that matches the selector is found.
+     *
      * See {@link #scrollDescriptionIntoView(String)} and {@link #scrollTextIntoView(String)}.
      *
      * @param selector {@link UiSelector} selector
-     * @return true if the item was found and now is in view else false
+     * @return true if the item was found and now is in view; else, false
      * @since API Level 16
      */
     public boolean scrollIntoView(UiSelector selector) throws UiObjectNotFoundException {
@@ -263,13 +279,13 @@ public class UiScrollable extends UiCollection {
     }
 
     /**
-     * Ensures the child object is fully visible in the scrollable container
+     * Scrolls forward until the UiObject is fully visible in the scrollable container.
+     * Use this method to make sure that the child item's edges are not offscreen.
      *
-     * Current implementation may actually scroll the item's edges off screen
-     * Current implementation does not check if the item can fully fit into the display area
-     *
-     * @param childSelector
-     * @return
+     * @param childObject {@link UiObject} representing the child element
+     * @return true if the child element is already fully visible, or 
+     * if the method scrolled successfully until the child became fully visible; 
+     * otherwise, false if the attempt to scroll failed.
      * @throws UiObjectNotFoundException
      * @hide
      */
@@ -306,11 +322,12 @@ public class UiScrollable extends UiCollection {
     }
 
     /**
-     * Performs a swipe up on the UI element until the requested text is visible
-     * or until swipe attempts have been exhausted. See {@link #setMaxSearchSwipes(int)}
+     * Performs a forward scroll action on the scrollable layout element until
+     * the text you provided is visible, or until swipe attempts have been exhausted.
+     * See {@link #setMaxSearchSwipes(int)}
      *
-     * @param text to look for
-     * @return true if item us found else false
+     * @param text test to look for
+     * @return true if item is found; else, false
      * @since API Level 16
      */
     public boolean scrollTextIntoView(String text) throws UiObjectNotFoundException {
@@ -319,13 +336,12 @@ public class UiScrollable extends UiCollection {
     }
 
     /**
-     * {@link #getChildByDescription(UiSelector, String)} and
-     * {@link #getChildByText(UiSelector, String)} use an arguments that specifies if scrolling is
-     * allowed while searching for the UI element.  The number of scrolls allowed to perform a
-     * search can be modified by this method.  The current value can be read by calling
-     * {@link #getMaxSearchSwipes()}
+     * Sets the maximum number of scrolls allowed when performing a
+     * scroll action in search of a child element.
+     * See {@link #getChildByDescription(UiSelector, String)} and
+     * {@link #getChildByText(UiSelector, String)}.
      *
-     * @param swipes is the number of search swipes until abort
+     * @param swipes the number of search swipes to perform until giving up
      * @return reference to itself
      * @since API Level 16
      */
@@ -336,13 +352,12 @@ public class UiScrollable extends UiCollection {
     }
 
     /**
-     * {@link #getChildByDescription(UiSelector, String)} and
-     * {@link #getChildByText(UiSelector, String)} use an arguments that specifies if scrolling is
-     * allowed while searching for the UI element.  The number of scrolls currently allowed to
-     * perform a search can be read by this method.
-     * See {@link #setMaxSearchSwipes(int)}
+     * Gets the maximum number of scrolls allowed when performing a
+     * scroll action in search of a child element.
+     * See {@link #getChildByDescription(UiSelector, String)} and
+     * {@link #getChildByText(UiSelector, String)}.
      *
-     * @return max value of the number of swipes currently allowed during a scroll search
+     * @return max the number of search swipes to perform until giving up
      * @since API Level 16
      */
     public int getMaxSearchSwipes() {
@@ -351,9 +366,14 @@ public class UiScrollable extends UiCollection {
     }
 
     /**
-     * A convenience version of {@link UiScrollable#scrollForward(int)}, performs a fling
-     *
-     * @return true if scrolled and false if can't scroll anymore
+     * Performs a forward fling with the default number of fling steps (5).
+     * If the swipe direction is set to vertical, then the swipes will be
+     * performed from bottom to top. If the swipe
+     * direction is set to horizontal, then the swipes will be performed from
+     * right to left. Make sure to take into account devices configured with
+     * right-to-left languages like Arabic and Hebrew.
+     *
+     * @return true if scrolled, false if can't scroll anymore
      * @since API Level 16
      */
     public boolean flingForward() throws UiObjectNotFoundException {
@@ -362,9 +382,14 @@ public class UiScrollable extends UiCollection {
     }
 
     /**
-     * A convenience version of {@link UiScrollable#scrollForward(int)}, performs a regular scroll
-     *
-     * @return true if scrolled and false if can't scroll anymore
+     * Performs a forward scroll with the default number of scroll steps (55).
+     * If the swipe direction is set to vertical,
+     * then the swipes will be performed from bottom to top. If the swipe
+     * direction is set to horizontal, then the swipes will be performed from
+     * right to left. Make sure to take into account devices configured with
+     * right-to-left languages like Arabic and Hebrew.
+     *
+     * @return true if scrolled, false if can't scroll anymore
      * @since API Level 16
      */
     public boolean scrollForward() throws UiObjectNotFoundException {
@@ -373,14 +398,14 @@ public class UiScrollable extends UiCollection {
     }
 
     /**
-     * Perform a scroll forward. If this list is set to vertical (see {@link #setAsVerticalList()}
-     * default) then the swipes will be executed from the bottom to top. If this list is set
-     * to horizontal (see {@link #setAsHorizontalList()}) then the swipes will be executed from
-     * the right to left. Caution is required on devices configured with right to left languages
-     * like Arabic and Hebrew.
-     *
-     * @param steps use steps to control the speed, so that it may be a scroll, or fling
-     * @return true if scrolled and false if can't scroll anymore
+     * Performs a forward scroll. If the swipe direction is set to vertical,
+     * then the swipes will be performed from bottom to top. If the swipe
+     * direction is set to horizontal, then the swipes will be performed from
+     * right to left. Make sure to take into account devices configured with
+     * right-to-left languages like Arabic and Hebrew.
+     *
+     * @param steps number of steps. Use this to control the speed of the scroll action
+     * @return true if scrolled, false if can't scroll anymore
      * @since API Level 16
      */
     public boolean scrollForward(int steps) throws UiObjectNotFoundException {
@@ -420,9 +445,14 @@ public class UiScrollable extends UiCollection {
     }
 
     /**
-     * See {@link UiScrollable#scrollBackward(int)}
-     *
-     * @return true if scrolled and false if can't scroll anymore
+     * Performs a backwards fling action with the default number of fling
+     * steps (5). If the swipe direction is set to vertical,
+     * then the swipe will be performed from top to bottom. If the swipe
+     * direction is set to horizontal, then the swipes will be performed from
+     * left to right. Make sure to take into account devices configured with
+     * right-to-left languages like Arabic and Hebrew.
+     *
+     * @return true if scrolled, and false if can't scroll anymore
      * @since API Level 16
      */
     public boolean flingBackward() throws UiObjectNotFoundException {
@@ -431,9 +461,14 @@ public class UiScrollable extends UiCollection {
     }
 
     /**
-     * See {@link UiScrollable#scrollBackward(int)}
-     *
-     * @return true if scrolled and false if can't scroll anymore
+     * Performs a backward scroll with the default number of scroll steps (55).
+     * If the swipe direction is set to vertical,
+     * then the swipes will be performed from top to bottom. If the swipe
+     * direction is set to horizontal, then the swipes will be performed from
+     * left to right. Make sure to take into account devices configured with
+     * right-to-left languages like Arabic and Hebrew.
+     *
+     * @return true if scrolled, and false if can't scroll anymore
      * @since API Level 16
      */
     public boolean scrollBackward() throws UiObjectNotFoundException {
@@ -442,14 +477,14 @@ public class UiScrollable extends UiCollection {
     }
 
     /**
-     * Perform a scroll backward. If this list is set to vertical (see {@link #setAsVerticalList()}
-     * default) then the swipes will be executed from the top to bottom. If this list is set
-     * to horizontal (see {@link #setAsHorizontalList()}) then the swipes will be executed from
-     * the left to right. Caution is required on devices configured with right to left languages
-     * like Arabic and Hebrew.
-     *
-     * @param steps use steps to control the speed, so that it may be a scroll, or fling
-     * @return true if scrolled and false if can't scroll anymore
+     * Performs a backward scroll. If the swipe direction is set to vertical,
+     * then the swipes will be performed from top to bottom. If the swipe
+     * direction is set to horizontal, then the swipes will be performed from
+     * left to right. Make sure to take into account devices configured with
+     * right-to-left languages like Arabic and Hebrew.
+     *
+     * @param steps number of steps. Use this to control the speed of the scroll action.
+     * @return true if scrolled, false if can't scroll anymore
      * @since API Level 16
      */
     public boolean scrollBackward(int steps) throws UiObjectNotFoundException {
@@ -491,9 +526,10 @@ public class UiScrollable extends UiCollection {
     }
 
     /**
-     * Scrolls to the beginning of a scrollable UI element. The beginning could be the top most
-     * in case of vertical lists or the left most in case of horizontal lists. Caution is required
-     * on devices configured with right to left languages like Arabic and Hebrew.
+     * Scrolls to the beginning of a scrollable layout element. The beginning
+     * can be at the  top-most edge in the case of vertical controls, or the
+     * left-most edge for horizontal controls. Make sure to take into account
+     * devices configured with right-to-left languages like Arabic and Hebrew.
      *
      * @param steps use steps to control the speed, so that it may be a scroll, or fling
      * @return true on scrolled else false
@@ -512,7 +548,10 @@ public class UiScrollable extends UiCollection {
     }
 
     /**
-     * See {@link UiScrollable#scrollToBeginning(int, int)}
+     * Scrolls to the beginning of a scrollable layout element. The beginning
+     * can be at the  top-most edge in the case of vertical controls, or the
+     * left-most edge for horizontal controls. Make sure to take into account
+     * devices configured with right-to-left languages like Arabic and Hebrew.
      *
      * @param maxSwipes
      * @return true on scrolled else false
@@ -524,7 +563,10 @@ public class UiScrollable extends UiCollection {
     }
 
     /**
-     * See {@link UiScrollable#scrollToBeginning(int, int)}
+     * Performs a fling gesture to reach the beginning of a scrollable layout element.
+     * The beginning can be at the  top-most edge in the case of vertical controls, or
+     * the left-most edge for horizontal controls. Make sure to take into
+     * account devices configured with right-to-left languages like Arabic and Hebrew.
      *
      * @param maxSwipes
      * @return true on scrolled else false
@@ -536,9 +578,10 @@ public class UiScrollable extends UiCollection {
     }
 
     /**
-     * Scrolls to the end of a scrollable UI element. The end could be the bottom most
-     * in case of vertical controls or the right most for horizontal controls. Caution
-     * is required on devices configured with right to left languages like Arabic and Hebrew.
+     * Scrolls to the end of a scrollable layout element. The end can be at the
+     * bottom-most edge in the case of vertical controls, or the right-most edge for
+     * horizontal controls. Make sure to take into account devices configured with
+     * right-to-left languages like Arabic and Hebrew.
      *
      * @param steps use steps to control the speed, so that it may be a scroll, or fling
      * @return true on scrolled else false
@@ -556,10 +599,13 @@ public class UiScrollable extends UiCollection {
     }
 
     /**
-     * See {@link UiScrollable#scrollToEnd(int, int)}
+     * Scrolls to the end of a scrollable layout element. The end can be at the
+     * bottom-most edge in the case of vertical controls, or the right-most edge for
+     * horizontal controls. Make sure to take into account devices configured with
+     * right-to-left languages like Arabic and Hebrew.
      *
      * @param maxSwipes
-     * @return true on scrolled else false
+     * @return true on scrolled, else false
      * @since API Level 16
      */
     public boolean scrollToEnd(int maxSwipes) throws UiObjectNotFoundException {
@@ -568,10 +614,13 @@ public class UiScrollable extends UiCollection {
     }
 
     /**
-     * See {@link UiScrollable#scrollToEnd(int, int)}
+     * Performs a fling gesture to reach the end of a scrollable layout element.
+     * The end can be at the  bottom-most edge in the case of vertical controls, or
+     * the right-most edge for horizontal controls. Make sure to take into
+     * account devices configured with right-to-left languages like Arabic and Hebrew.
      *
      * @param maxSwipes
-     * @return true on scrolled else false
+     * @return true on scrolled, else false
      * @since API Level 16
      */
     public boolean flingToEnd(int maxSwipes) throws UiObjectNotFoundException {
@@ -580,15 +629,12 @@ public class UiScrollable extends UiCollection {
     }
 
     /**
-     * Returns the percentage of a widget's size that's considered as no touch zone when swiping
-     *
-     * Dead zones are set as percentage of a widget's total width or height where
-     * swipe start point cannot start or swipe end point cannot end. It is like a margin
-     * around the actual dimensions of the widget. Swipes will always be start and
-     * end inside this margin.
-     *
-     * This is important when the widget being swiped may not respond to the swipe if
-     * started at a point too near to the edge. The default is 10% from either edge.
+     * Returns the percentage of a widget's size that's considered as a no-touch
+     * zone when swiping. The no-touch zone is set as a percentage of a widget's total
+     * width or height, denoting a margin around the swipable area of the widget.
+     * Swipes must start and end inside this margin. This is important when the
+     * widget being swiped may not respond to the swipe if started at a point
+     * too near to the edge. The default is 10% from either edge.
      *
      * @return a value between 0 and 1
      * @since API Level 16
@@ -599,15 +645,13 @@ public class UiScrollable extends UiCollection {
     }
 
     /**
-     * Sets the percentage of a widget's size that's considered as no touch zone when swiping
-     *
-     * Dead zones are set as percentage of a widget's total width or height where
-     * swipe start point cannot start or swipe end point cannot end. It is like a margin
-     * around the actual dimensions of the widget. Swipes will always start and
-     * end inside this margin.
-     *
-     * This is important when the widget being swiped may not respond to the swipe if
-     * started at a point too near to the edge. The default is 10% from either edge
+     * Sets the percentage of a widget's size that's considered as no-touch
+     * zone when swiping.
+     * The no-touch zone is set as percentage of a widget's total width or height,
+     * denoting a margin around the swipable area of the widget. Swipes must
+     * always start and end inside this margin. This is important when the
+     * widget being swiped may not respond to the swipe if started at a point
+     * too near to the edge. The default is 10% from either edge.
      *
      * @param swipeDeadZonePercentage is a value between 0 and 1
      * @return reference to itself
@@ -618,4 +662,4 @@ public class UiScrollable extends UiCollection {
         mSwipeDeadZonePercentage = swipeDeadZonePercentage;
         return this;
     }
-}
+
diff --git a/library/core-src/com/android/uiautomator/core/UiSelector.java b/library/core-src/com/android/uiautomator/core/UiSelector.java
index b7f5fa7..a3b5c54 100644
--- a/library/core-src/com/android/uiautomator/core/UiSelector.java
+++ b/library/core-src/com/android/uiautomator/core/UiSelector.java
@@ -22,12 +22,10 @@ import android.view.accessibility.AccessibilityNodeInfo;
 import java.util.regex.Pattern;
 
 /**
- * This class provides the mechanism for tests to describe the UI elements they
- * intend to target. A UI element has many properties associated with it such as
- * text value, content-description, class name and multiple state information like
- * selected, enabled, checked etc. Additionally UiSelector allows targeting of UI
- * elements within a specific display hierarchies to distinguish similar elements
- * based in the hierarchies they're in.
+ * Specifies the elements in the layout hierarchy for tests to target, filtered
+ * by properties such as text value, content-description, class name, and state
+ * information. You can also target an element by its location in a layout
+ * hierarchy.
  * @since API Level 16
  */
 public class UiSelector {
@@ -105,11 +103,10 @@ public class UiSelector {
 
     /**
      * Set the search criteria to match the visible text displayed
-     * for a widget (for example, the text label to launch an app).
+     * in a widget (for example, the text label to launch an app).
      *
-     * The text for the widget must match exactly
-     * with the string in your input argument.
-     * Matching is case-sensitive.
+     * The text for the element must match exactly with the string in your input
+     * argument. Matching is case-sensitive.
      *
      * @param text Value to match
      * @return UiSelector with the specified search criteria
@@ -120,11 +117,11 @@ public class UiSelector {
     }
 
     /**
-     * Set the search criteria to match the visible text displayed
-     * for a widget (for example, the text label to launch an app).
+     * Set the search criteria to match the visible text displayed in a layout
+     * element, using a regular expression.
      *
-     * The text for the widget must match exactly
-     * with the string in your input argument.
+     * The text in the widget must match exactly with the string in your
+     * input argument.
      *
      * @param regex a regular expression
      * @return UiSelector with the specified search criteria
@@ -135,15 +132,13 @@ public class UiSelector {
     }
 
     /**
-     * Text property is usually the widget's visible text on the display.
-     *
-     * Adding this to the search criteria indicates that the search performed
-     * should match a widget with text value starting with the text parameter.
+     * Set the search criteria to match visible text in a widget that is
+     * prefixed by the text parameter.
      *
-     * The matching will be case-insensitive.
+     * The matching is case-insensitive.
      *
-     * @param text
-     * @return UiSelector with this added search criterion
+     * @param text Value to match
+     * @return UiSelector with the specified search criteria
      * @since API Level 16
      */
     public UiSelector textStartsWith(String text) {
@@ -151,11 +146,10 @@ public class UiSelector {
     }
 
     /**
-     * Set the search criteria to match the visible text displayed
-     * for a widget (for example, the text label to launch an app).
+     * Set the search criteria to match the visible text in a widget
+     * where the visible text must contain the string in your input argument.
      *
-     * The text for the widget must contain the string in
-     * your input argument. Matching is case-sensitive.
+     * The matching is case-sensitive.
      *
      * @param text Value to match
      * @return UiSelector with the specified search criteria
@@ -179,7 +173,7 @@ public class UiSelector {
 
     /**
      * Set the search criteria to match the class property
-     * for a widget (for example, "android.widget.Button").
+     * for a widget, using a regular expression.
      *
      * @param regex a regular expression
      * @return UiSelector with the specified search criteria
@@ -284,9 +278,9 @@ public class UiSelector {
     }
 
     /**
-     * Set the search criteria to match the given resource id.
+     * Set the search criteria to match the given resource ID.
      *
-     * @param id value to match
+     * @param id Value to match
      * @return UiSelector with the specified search criteria
      * @since API Level 18
      */
@@ -295,8 +289,8 @@ public class UiSelector {
     }
 
     /**
-     * Set the search criteria to match the resourceId
-     * of the widget
+     * Set the search criteria to match the resource ID
+     * of the widget, using a regular expression.http://blog.bettersoftwaretesting.com/
      *
      * @param regex a regular expression
      * @return UiSelector with the specified search criteria
@@ -1025,4 +1019,4 @@ public class UiSelector {
         builder.append("]");
         return builder.toString();
     }
-}
+