Fix the remaining JavaDoc warnings
We should have a consistent style for JavaDoc, i.e. @param for all
parameters of a method, or none. And a consistent format. I used
"Reformat code" from Android Studio on some files I touched in this cl.
Now the consistency is only on a per-file basis. We may apply it
incrementally.
Change-Id: Icfe2ef223d93e78e42b400a1dd2b50a0ef19a13a
diff --git a/build.gradle b/build.gradle
index 5b20679..47af871 100644
--- a/build.gradle
+++ b/build.gradle
@@ -107,7 +107,11 @@
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 @@
/**
* 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 @@
* @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 @@
/**
* 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 @@
*
* @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 @@
*/
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 @@
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 @@
*/
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);
}
