am 3fff05fc: Merge "Fix the remaining JavaDoc warnings"

* commit '3fff05fc560b8716ead506941eaaa7ba6b47bdd7':
  Fix the remaining JavaDoc warnings

7 files changed, 44 insertions, 53 deletions

diff --git a/build.gradle b/build.gradle
index 5b20679..47af871 100644
--- a/build.gradle
+++ b/build.gradle
@@ -107,7 +107,11 @@ task sourcesJar(type: Jar) {
 task javadoc(type: Javadoc) {
     source = android.sourceSets.main.java.srcDirs
     classpath += project.files(android.getBootClasspath().join(File.pathSeparator))
-    if (System.getProperties().get('java.specification.version') == '1.8') {
+    if (System.getProperty('java.specification.version') == '1.8') {
+        // '-quiet' is not related to -Xdoclint. In fact it is default for the Javadoc task.
+        // It is needed here because of a Gradle bug: addStringOption(String option) does not work.
+        // addStringOption(String option, String value) adds both option and value to the generated
+        // file javadoc.options, and value must be a valid javadoc command line option.
         options.addStringOption('Xdoclint:all,-missing', '-quiet')
     }
 }
diff --git a/src/com/google/android/droiddriver/UiElement.java b/src/com/google/android/droiddriver/UiElement.java
index f53c22a..571f3bc 100644
--- a/src/com/google/android/droiddriver/UiElement.java
+++ b/src/com/google/android/droiddriver/UiElement.java
@@ -181,8 +181,7 @@ public interface UiElement {
   /**
    * Scrolls in the given direction.
    *
-   * @param direction specifies where the view port will move, instead of the
-   *        finger.
+   * @param direction specifies where the view port will move instead of the finger
    */
   void scroll(PhysicalDirection direction);
 
diff --git a/src/com/google/android/droiddriver/actions/SwipeAction.java b/src/com/google/android/droiddriver/actions/SwipeAction.java
index 6837741..b5818cb 100644
--- a/src/com/google/android/droiddriver/actions/SwipeAction.java
+++ b/src/com/google/android/droiddriver/actions/SwipeAction.java
@@ -122,7 +122,7 @@ public class SwipeAction extends EventAction implements ScrollAction {
    * @param steps minimum 2; (steps-1) is the number of {@code ACTION_MOVE} that
    *        will be injected between {@code ACTION_DOWN} and {@code ACTION_UP}.
    * @param drag whether this is a drag
-   * @param timeoutMillis
+   * @param timeoutMillis the value returned by {@link #getTimeoutMillis}
    * @param topMarginRatio margin ratio from top
    * @param leftMarginRatio margin ratio from left
    * @param bottomMarginRatio margin ratio from bottom
diff --git a/src/com/google/android/droiddriver/helpers/PollingListeners.java b/src/com/google/android/droiddriver/helpers/PollingListeners.java
index 44cd826..154818f 100644
--- a/src/com/google/android/droiddriver/helpers/PollingListeners.java
+++ b/src/com/google/android/droiddriver/helpers/PollingListeners.java
@@ -12,6 +12,7 @@ public class PollingListeners {
   /**
    * Tries to find {@code watchFinder}, and clicks it if found.
    *
+   * @param driver a DroidDriver instance
    * @param watchFinder Identifies the UI component to watch
    * @return whether {@code watchFinder} is found
    */
diff --git a/src/com/google/android/droiddriver/helpers/ScrollerHelper.java b/src/com/google/android/droiddriver/helpers/ScrollerHelper.java
index 74059ad..c6cc4a4 100644
--- a/src/com/google/android/droiddriver/helpers/ScrollerHelper.java
+++ b/src/com/google/android/droiddriver/helpers/ScrollerHelper.java
@@ -56,7 +56,7 @@ public class ScrollerHelper {
    *
    * @param itemFinder Finder for the desired item; relative to
    *        {@code containerFinder}
-   * @param direction
+   * @param direction specifies where the view port will move instead of the finger
    * @return the UiElement matching {@code itemFinder}
    * @throws ElementNotFoundException If no match is found
    */
diff --git a/src/com/google/android/droiddriver/scroll/ScrollStepStrategy.java b/src/com/google/android/droiddriver/scroll/ScrollStepStrategy.java
index 9583def..8e3ddc3 100644
--- a/src/com/google/android/droiddriver/scroll/ScrollStepStrategy.java
+++ b/src/com/google/android/droiddriver/scroll/ScrollStepStrategy.java
@@ -26,13 +26,12 @@ import com.google.android.droiddriver.scroll.Direction.PhysicalDirection;
  */
 public interface ScrollStepStrategy {
   /**
-   * Tries to scroll {@code containerFinder} in {@code direction}. Returns
-   * whether scrolling is effective.
+   * Tries to scroll {@code containerFinder} in {@code direction}. Returns whether scrolling is
+   * effective.
    *
-   * @param driver
-   * @param containerFinder Finder for the container that can scroll, for
-   *        instance a ListView
-   * @param direction
+   * @param driver          a DroidDriver instance
+   * @param containerFinder Finder for the container that can scroll, for instance a ListView
+   * @param direction       specifies where the view port will move instead of the finger
    * @return whether scrolling is effective
    */
   boolean scroll(DroidDriver driver, Finder containerFinder, PhysicalDirection direction);
@@ -43,48 +42,40 @@ public interface ScrollStepStrategy {
   DirectionConverter getDirectionConverter();
 
   /**
-   * Called only if this step is at the beginning of a series of scroll steps
-   * with regard to the given arguments.
+   * Called only if this step is at the beginning of a series of scroll steps with regard to the
+   * given arguments.
    *
-   * @param driver
-   * @param containerFinder Finder for the container that can scroll, for
-   *        instance a ListView
-   * @param itemFinder Finder for the desired item; relative to
-   *        {@code containerFinder}
-   * @param direction
+   * @param driver          a DroidDriver instance
+   * @param containerFinder Finder for the container that can scroll, for instance a ListView
+   * @param itemFinder      Finder for the desired item; relative to {@code containerFinder}
+   * @param direction       specifies where the view port will move instead of the finger
    */
   void beginScrolling(DroidDriver driver, Finder containerFinder, Finder itemFinder,
-      PhysicalDirection direction);
+                      PhysicalDirection direction);
 
   /**
-   * Called only if this step is at the end of a series of scroll steps with
-   * regard to the given arguments.
+   * Called only if this step is at the end of a series of scroll steps with regard to the given
+   * arguments.
    *
-   * @param driver
-   * @param containerFinder Finder for the container that can scroll, for
-   *        instance a ListView
-   * @param itemFinder Finder for the desired item; relative to
-   *        {@code containerFinder}
-   * @param direction
+   * @param driver          a DroidDriver instance
+   * @param containerFinder Finder for the container that can scroll, for instance a ListView
+   * @param itemFinder      Finder for the desired item; relative to {@code containerFinder}
+   * @param direction       specifies where the view port will move instead of the finger
    */
   void endScrolling(DroidDriver driver, Finder containerFinder, Finder itemFinder,
-      PhysicalDirection direction);
+                    PhysicalDirection direction);
 
   /**
-   * Performs the scroll action on {@code container}. Subclasses can override
-   * this to customize the scroll action, for example, to adjust the scroll
-   * margins.
+   * Performs the scroll action on {@code container}. Subclasses can override this to customize the
+   * scroll action, for example, to adjust the scroll margins.
    *
    * @param container the container that can scroll
-   * @param direction
+   * @param direction specifies where the view port will move instead of the finger
    */
   void doScroll(UiElement container, PhysicalDirection direction);
 
   /**
-   * {@inheritDoc}
-   *
-   * <p>
-   * It is recommended that this method return a description to help debugging.
+   * {@inheritDoc} It is recommended that this method return a description to help debugging.
    */
   @Override
   String toString();
diff --git a/src/com/google/android/droiddriver/scroll/Scroller.java b/src/com/google/android/droiddriver/scroll/Scroller.java
index f94f784..277123b 100644
--- a/src/com/google/android/droiddriver/scroll/Scroller.java
+++ b/src/com/google/android/droiddriver/scroll/Scroller.java
@@ -26,32 +26,28 @@ import com.google.android.droiddriver.scroll.Direction.PhysicalDirection;
  */
 public interface Scroller {
   /**
-   * Scrolls {@code containerFinder} in both directions if necessary to find
-   * {@code itemFinder}, which is a descendant of {@code containerFinder}.
+   * Scrolls {@code containerFinder} in both directions if necessary to find {@code itemFinder},
+   * which is a descendant of {@code containerFinder}.
    *
-   * @param driver
-   * @param containerFinder Finder for the container that can scroll, for
-   *        instance a ListView
-   * @param itemFinder Finder for the desired item; relative to
-   *        {@code containerFinder}
+   * @param driver          a DroidDriver instance
+   * @param containerFinder Finder for the container that can scroll, for instance a ListView
+   * @param itemFinder      Finder for the desired item; relative to {@code containerFinder}
    * @return the UiElement matching {@code itemFinder}
    * @throws ElementNotFoundException If no match is found
    */
   UiElement scrollTo(DroidDriver driver, Finder containerFinder, Finder itemFinder);
 
   /**
-   * Scrolls {@code containerFinder} in {@code direction} if necessary to find
-   * {@code itemFinder}, which is a descendant of {@code containerFinder}.
+   * Scrolls {@code containerFinder} in {@code direction} if necessary to find {@code itemFinder},
+   * which is a descendant of {@code containerFinder}.
    *
-   * @param driver
-   * @param containerFinder Finder for the container that can scroll, for
-   *        instance a ListView
-   * @param itemFinder Finder for the desired item; relative to
-   *        {@code containerFinder}
-   * @param direction
+   * @param driver          a DroidDriver instance
+   * @param containerFinder Finder for the container that can scroll, for instance a ListView
+   * @param itemFinder      Finder for the desired item; relative to {@code containerFinder}
+   * @param direction       specifies where the view port will move instead of the finger
    * @return the UiElement matching {@code itemFinder}
    * @throws ElementNotFoundException If no match is found
    */
   UiElement scrollTo(DroidDriver driver, Finder containerFinder, Finder itemFinder,
-      PhysicalDirection direction);
+                     PhysicalDirection direction);
 }