fixed remaining public API javadocs - closes seleniumQuery#75

acdcjunior · acdcjunior · commit 4ed5069c0396 · 2014-11-30T22:51:11.000-02:00
diff --git a/src/main/java/io/github/seleniumquery/SeleniumQueryObject.java b/src/main/java/io/github/seleniumquery/SeleniumQueryObject.java
diff --git a/src/main/java/io/github/seleniumquery/by/css/attributes/ClassAttributeCssSelector.java b/src/main/java/io/github/seleniumquery/by/css/attributes/ClassAttributeCssSelector.java
@@ -18,14 +18,15 @@
  * .class
  *
  * @author acdcjunior
+ *
  * @since 0.9.0
  */
 public class ClassAttributeCssSelector implements CssConditionalSelector<AttributeCondition> {
 
 	private static final String CLASS_ATTRIBUTE = "class";
 	
 	/**
-	 * @see {@link org.w3c.css.sac.Condition#SAC_CLASS_CONDITION}
+	 * see {@link org.w3c.css.sac.Condition#SAC_CLASS_CONDITION}
 	 *
 	 * This condition checks for a specified class. Example: .example
 	 */
diff --git a/src/main/java/io/github/seleniumquery/by/css/attributes/ContainsPrefixAttributeCssSelector.java b/src/main/java/io/github/seleniumquery/by/css/attributes/ContainsPrefixAttributeCssSelector.java
@@ -18,12 +18,13 @@
  * [languages|="fr"]
  *
  * @author acdcjunior
+ *
  * @since 0.9.0
  */
 public class ContainsPrefixAttributeCssSelector implements CssConditionalSelector<AttributeCondition> {
 
 	/**
-	 * @see {@link org.w3c.css.sac.Condition#SAC_BEGIN_HYPHEN_ATTRIBUTE_CONDITION}
+	 * see {@link org.w3c.css.sac.Condition#SAC_BEGIN_HYPHEN_ATTRIBUTE_CONDITION}
 	 *
 	 * This condition checks if the value is in a hypen-separated list of values in a specified attribute. example:
 	 * [languages|="fr"]
diff --git a/src/main/java/io/github/seleniumquery/by/css/attributes/ContainsWordAttributeCssSelector.java b/src/main/java/io/github/seleniumquery/by/css/attributes/ContainsWordAttributeCssSelector.java
@@ -17,14 +17,15 @@
  * [values~="10"]
  *
  * @author acdcjunior
+ *
  * @since 0.9.0
  */
 public class ContainsWordAttributeCssSelector implements CssConditionalSelector<AttributeCondition> {
 
 	public static final String CONTAINS_WORD_ATTRIBUTE_SELECTOR_SYMBOL = "~=";
 	
 	/**
-	 * @see {@link org.w3c.css.sac.Condition#SAC_ONE_OF_ATTRIBUTE_CONDITION}
+	 * see {@link org.w3c.css.sac.Condition#SAC_ONE_OF_ATTRIBUTE_CONDITION}
 	 * 
 	 * This condition checks for a value in a space-separated values in a specified attribute example:
 	 * [values~="10"]
diff --git a/src/main/java/io/github/seleniumquery/by/css/attributes/EqualsOrHasAttributeCssSelector.java b/src/main/java/io/github/seleniumquery/by/css/attributes/EqualsOrHasAttributeCssSelector.java
@@ -30,7 +30,7 @@ public class EqualsOrHasAttributeCssSelector implements CssConditionalSelector<A
 	public static final String EQUALS_ATTRIBUTE_SELECTOR_SYMBOL = "=";
 
 	/**
-	 * @see {@link org.w3c.css.sac.Condition#SAC_ATTRIBUTE_CONDITION}
+	 * see {@link org.w3c.css.sac.Condition#SAC_ATTRIBUTE_CONDITION}
 	 * 
 	 * This condition checks an attribute. example:
 	 * 
diff --git a/src/main/java/io/github/seleniumquery/by/css/attributes/IdAttributeCssSelector.java b/src/main/java/io/github/seleniumquery/by/css/attributes/IdAttributeCssSelector.java
@@ -16,14 +16,15 @@
  * #id
  *
  * @author acdcjunior
+ *
  * @since 0.9.0
  */
 public class IdAttributeCssSelector implements CssConditionalSelector<AttributeCondition> {
 
 	private static final String ID_ATTRIBUTE = "id";
 
 	/**
-	 * @see {@link org.w3c.css.sac.Condition#SAC_ID_CONDITION}
+	 * see {@link org.w3c.css.sac.Condition#SAC_ID_CONDITION}
 	 * 
 	 * This condition checks an id attribute. Example:
 	 * 
diff --git a/src/main/java/io/github/seleniumquery/by/css/conditionals/AndConditionalCssSelector.java b/src/main/java/io/github/seleniumquery/by/css/conditionals/AndConditionalCssSelector.java
@@ -17,9 +17,10 @@
 /**
  * E.firstCondition.secondCondition
  *
- * @see {@link Condition#SAC_AND_CONDITION}
+ * see {@link Condition#SAC_AND_CONDITION}
  *
  * @author acdcjunior
+ *
  * @since 0.9.0
  */
 public class AndConditionalCssSelector implements CssConditionalSelector<CombinatorCondition> {
diff --git a/src/main/java/io/github/seleniumquery/by/css/pseudoclasses/FilePseudoClass.java b/src/main/java/io/github/seleniumquery/by/css/pseudoclasses/FilePseudoClass.java
@@ -4,6 +4,7 @@
  * http://api.jquery.com/file-selector/
  * 
  * @since 0.9.0
+ *
  * @author acdcjunior
  */
 public class FilePseudoClass extends InputTypeAttributePseudoClass {
diff --git a/src/main/java/io/github/seleniumquery/by/css/pseudoclasses/FocusablePseudoClass.java b/src/main/java/io/github/seleniumquery/by/css/pseudoclasses/FocusablePseudoClass.java
@@ -8,7 +8,7 @@
 import org.openqa.selenium.WebElement;
 
 /**
- * @ see http://api.jqueryui.com/focusable-selector/
+ * see -> http://api.jqueryui.com/focusable-selector/
  * No browser supports :focusable natively.
  * 
  * Some elements are natively focusable, while others require explicitly setting a tab index. In all cases, the element must be visible in order to be focusable.
@@ -23,6 +23,7 @@
  * - ALL OTHER elements are focusable based solely on their tabindex attribute and visibility.
  * 
  * @author acdcjunior
+ *
  * @since 0.9.0
  */
 public class FocusablePseudoClass implements PseudoClass {
diff --git a/src/main/java/io/github/seleniumquery/wait/SeleniumQueryAndOrThen.java b/src/main/java/io/github/seleniumquery/wait/SeleniumQueryAndOrThen.java
@@ -2,6 +2,14 @@
 
 import io.github.seleniumquery.SeleniumQueryObject;
 
+/**
+ * A builder class that allows to specify the next step after waiting for some condition: to wait for more
+ * (<code>.and()</code>) or to do something else (<code>.then()</code>).
+ *
+ * @author acdcjunior
+ *
+ * @since 0.9.0
+ */
 public class SeleniumQueryAndOrThen {
 	
 	private SeleniumQueryObject seleniumQueryObject;
@@ -10,10 +18,23 @@ public SeleniumQueryAndOrThen(SeleniumQueryObject seleniumQueryObject) {
 		this.seleniumQueryObject = seleniumQueryObject;
 	}
 
+	/**
+	 * Allows the chaining of additional waiting conditions.
+	 *
+	 * @return An object where it is possible to set more waiting conditions.
+	 *
+	 * @since 0.9.0
+	 */
 	public SeleniumQueryWaitUntil and() {
 		return new SeleniumQueryWaitUntil(this.seleniumQueryObject);
 	}
-	
+
+	/**
+	 * Allows the execution of a regular function (such as <code>.click()</code>) on the elements matched after
+	 * the waiting condition is met.
+	 *
+ 	 * @return The {@link SeleniumQueryObject} after the waiting conditions were met.
+	 */
 	public SeleniumQueryObject then() {
 		return this.seleniumQueryObject;
 	}
diff --git a/src/main/java/io/github/seleniumquery/wait/SeleniumQueryEvaluateUntil.java b/src/main/java/io/github/seleniumquery/wait/SeleniumQueryEvaluateUntil.java
@@ -13,6 +13,8 @@
  * @author acdcjunior
  *
  * @param <T> The type returned by the getter and TYPE OF THE ARGUMENT used in the end function.
+ *
+ * @since 0.9.0
  */
 public class SeleniumQueryEvaluateUntil<T> {
 	
@@ -32,34 +34,82 @@ private SeleniumQueryEvaluateUntil(SeleniumQueryFluentWait fluentWait, Getter<T>
 		this.negated = negated;
 	}
 
+	/**
+	 * <p>Tests if the result of the preceding function is equal to the given argument.</p>
+	 * <b>If you want to test for inequality, use <code>.not().isEqualTo()</code>.</b>
+	 *
+	 * @param valueToEqual The value the function call result must be equal to.
+	 * @return An element that allows chaining of further waiting conditions or calling regular functions.
+	 *
+	 * @since 0.9.0
+	 */
 	public SeleniumQueryAndOrThen isEqualTo(T valueToEqual) {
 		Evaluator<T> equalsEvaluator = new EqualsEvaluator<T>(getter);
 		SeleniumQueryObject sq = fluentWait.waitUntil(equalsEvaluator, valueToEqual, seleniumQueryObject, this.negated);
 		return new SeleniumQueryAndOrThen(sq);
 	}
-	
+
+	/**
+	 * Tests if the result of the preceding function contains the given argument.
+	 *
+	 * @param string The string the function call result must contain.
+	 * @return An element that allows chaining of further waiting conditions or calling regular functions.
+	 *
+	 * @since 0.9.0
+	 */
 	public SeleniumQueryAndOrThen contains(String string) {
 		Evaluator<String> containsEvaluator = new ContainsEvaluator(getter);
 		return new SeleniumQueryAndOrThen(fluentWait.waitUntil(containsEvaluator, string, seleniumQueryObject, this.negated));
 	}
-	
+
+	/**
+	 * Tests if the result of the preceding function matches the given regex.
+	 *
+	 * @param regex The regex the function call result must match.
+	 * @return An element that allows chaining of further waiting conditions or calling regular functions.
+	 *
+	 * @since 0.9.0
+	 */
 	public SeleniumQueryAndOrThen matches(String regex) {
 		Evaluator<String> matchesEvaluator = new MatchesEvaluator(getter);
 		return new SeleniumQueryAndOrThen(fluentWait.waitUntil(matchesEvaluator, regex, seleniumQueryObject, this.negated));
 	}
-	
+
+	/**
+	 * <p>Tests if the result of the preceding function is greater than the given argument.</p>
+	 *
+	 * @param valueToCompare The number the function call result must be greater than.
+	 * @return An element that allows chaining of further waiting conditions or calling regular functions.
+	 *
+	 * @since 0.9.0
+	 */
 	public SeleniumQueryAndOrThen isGreaterThan(Number valueToCompare) {
 		Evaluator<Number> greaterThanEvaluator = new GreaterThanEvaluator(getter);
 		SeleniumQueryObject sq = fluentWait.waitUntil(greaterThanEvaluator, valueToCompare, seleniumQueryObject, this.negated);
 		return new SeleniumQueryAndOrThen(sq);
 	}
-	
+
+	/**
+	 * <p>Tests if the result of the preceding function is less than the given argument.</p>
+	 *
+	 * @param valueToCompare The number the function call result must be less than.
+	 * @return An element that allows chaining of further waiting conditions or calling regular functions.
+	 *
+	 * @since 0.9.0
+	 */
 	public SeleniumQueryAndOrThen isLessThan(Number valueToCompare) {
 		Evaluator<Number> lessThanEvaluator = new LessThanEvaluator(getter);
 		SeleniumQueryObject sq = fluentWait.waitUntil(lessThanEvaluator, valueToCompare, seleniumQueryObject, this.negated);
 		return new SeleniumQueryAndOrThen(sq);
 	}
-	
+
+	/**
+	 * Negates the criteria that follows.
+	 *
+	 * @return An object for specifying the criteria which the function call result must <b>NOT</b> meet.
+	 *
+	 * @since 0.9.0
+	 */
 	public SeleniumQueryEvaluateUntil<T> not() {
 		return new SeleniumQueryEvaluateUntil<T>(fluentWait, getter, seleniumQueryObject, !this.negated);
 	}
diff --git a/src/main/java/io/github/seleniumquery/wait/SeleniumQueryWaitUntil.java b/src/main/java/io/github/seleniumquery/wait/SeleniumQueryWaitUntil.java
@@ -12,6 +12,7 @@
 
 /**
  * @author acdcjunior
+ *
  * @since 0.9.0
  */
 public class SeleniumQueryWaitUntil {
@@ -48,36 +49,80 @@ public SeleniumQueryWaitUntil(SeleniumQueryObject seleniumQueryObject, long wait
 	}
 	
 	/**
-	 * Requeries the DOM <strong>until at least one element returned</strong> by a query to the selector used
-	 * to construct this seleniumQuery object <strong>is matched by the selector given</strong>.
+	 * Waits until <b>at least one element returned</b> - by a query to the selector used
+	 * to construct this seleniumQuery object - <b>is matched by the selector given</b>.
+	 *
+	 * @return An object for specifying other waiting conditions (<code>.and()</code>) or to execute usual functions (<code>.then()</code>).
 	 * 
 	 * @since 0.9.0
 	 */
 	public SeleniumQueryAndOrThen is(String selector) {
 		SeleniumQueryObject seleniumQueryObjectAfterWait = this.fluentWait.waitUntil(IsEvaluator.IS_EVALUATOR, selector, seleniumQueryObject, false);
 		return new SeleniumQueryAndOrThen(seleniumQueryObjectAfterWait);
 	}
-	
+
+	/**
+	 * Waits until every matched element's value meets the specified criteria.
+	 *
+	 * @return An object for specifying the criteria which the values of the elements must meet.
+	 *
+	 * @since 0.9.0
+	 */
 	public SeleniumQueryEvaluateUntil<String> val() {
 		return new SeleniumQueryEvaluateUntil<String>(this.fluentWait, ValGetter.VAL_GETTER, seleniumQueryObject);
 	}
-	
+
+	/**
+	 * Waits until every matched element's text meets the specified criteria.
+	 *
+	 * @return An object for specifying the criteria which the texts of the elements must meet.
+	 *
+	 * @since 0.9.0
+	 */
 	public SeleniumQueryEvaluateUntil<String> text() {
 		return new SeleniumQueryEvaluateUntil<String>(this.fluentWait, TextGetter.TEXT_GETTER, seleniumQueryObject);
 	}
-	
+
+	/**
+	 * Waits until every matched element has the given attribute meeting the specified criteria.
+	 *
+	 * @return An object for specifying the criteria which the attributes of the elements must meet.
+	 *
+	 * @since 0.9.0
+	 */
 	public SeleniumQueryEvaluateUntil<String> attr(String attributeName) {
 		return new SeleniumQueryEvaluateUntil<String>(this.fluentWait, new AttrGetter(attributeName), seleniumQueryObject);
 	}
-	
+
+	/**
+	 * Waits until every matched element has the given attribute property the specified criteria.
+	 *
+	 * @return An object for specifying the criteria which the properties of the elements must meet.
+	 *
+	 * @since 0.9.0
+	 */
 	public <T> SeleniumQueryEvaluateUntil<T> prop(String propertyName) {
 		return new SeleniumQueryEvaluateUntil<T>(this.fluentWait, new PropGetter<T>(propertyName), seleniumQueryObject);
 	}
-	
+
+	/**
+	 * Waits until every matched element's html meets the specified criteria.
+	 *
+	 * @return An object for specifying the criteria which the htmls of the elements must meet.
+	 *
+	 * @since 0.9.0
+	 */
 	public SeleniumQueryEvaluateUntil<String> html() {
 		return new SeleniumQueryEvaluateUntil<String>(this.fluentWait, HtmlGetter.HTML_GETTER, seleniumQueryObject);
 	}
-	
+
+	/**
+	 * Waits until the quantity of matched elements meets the specified criteria.
+	 *
+	 * @return An object for specifying the criteria which the quantity of the elements must meet.
+	 *
+	 * @since 0.9.0
+	 */
 	public SeleniumQueryEvaluateUntil<Integer> size() {
 		return new SeleniumQueryEvaluateUntil<Integer>(this.fluentWait, SizeGetter.SIZE_GETTER, seleniumQueryObject);
 	}
diff --git a/src/test/java/infrastructure/junitrule/SetUpAndTearDownDriver.java b/src/test/java/infrastructure/junitrule/SetUpAndTearDownDriver.java
@@ -7,7 +7,7 @@
 
 public class SetUpAndTearDownDriver implements TestRule {
 
-	private static final DriverToRunTestsIn driverToRunTestsIn = DriverToRunTestsIn.FIREFOX_WITH_JS_OFF_AS_WELL;
+	private static final DriverToRunTestsIn driverToRunTestsIn = DriverToRunTestsIn.PHANTOMJS;
 
 	private final Class<?> htmlTestUrlClass;
 
diff --git a/src/test/java/integration/waitUntil/WaitUntilValTest.html b/src/test/java/integration/waitUntil/WaitUntilValTest.html
@@ -0,0 +1,9 @@
+<!DOCTYPE html>
+<html>
+<head><meta charset="utf-8"><title>.waitUntil().val() test page</title>
+</head>
+<body>
+    <input type="text" id="i1">
+    <input type="text" id="i2">
+</body>
+</html>
diff --git a/src/test/java/integration/waitUntil/WaitUntilValTest.java b/src/test/java/integration/waitUntil/WaitUntilValTest.java

Original file line number	Diff line number	Diff line change
`@@ -18,12 +18,13 @@`
`18`	`18`	`* [languages\|="fr"]`
`19`	`19`	`*`
`20`	`20`	`* @author acdcjunior`
	`21`	`+ *`
`21`	`22`	`* @since 0.9.0`
`22`	`23`	`*/`
`23`	`24`	`public class ContainsPrefixAttributeCssSelector implements CssConditionalSelector<AttributeCondition> {`
`24`	`25`
`25`	`26`	`/**`
`26`		`- * @see {@link org.w3c.css.sac.Condition#SAC_BEGIN_HYPHEN_ATTRIBUTE_CONDITION}`
	`27`	`+ * see {@link org.w3c.css.sac.Condition#SAC_BEGIN_HYPHEN_ATTRIBUTE_CONDITION}`
`27`	`28`	`*`
`28`	`29`	`* This condition checks if the value is in a hypen-separated list of values in a specified attribute. example:`
`29`	`30`	`* [languages\|="fr"]`
Original file line number	Diff line number	Diff line change
`@@ -30,7 +30,7 @@ public class EqualsOrHasAttributeCssSelector implements CssConditionalSelector<A`
`30`	`30`	`public static final String EQUALS_ATTRIBUTE_SELECTOR_SYMBOL = "=";`
`31`	`31`
`32`	`32`	`/**`
`33`		`- * @see {@link org.w3c.css.sac.Condition#SAC_ATTRIBUTE_CONDITION}`
	`33`	`+ * see {@link org.w3c.css.sac.Condition#SAC_ATTRIBUTE_CONDITION}`
`34`	`34`	`*`
`35`	`35`	`* This condition checks an attribute. example:`
`36`	`36`	`*`
Original file line number	Diff line number	Diff line change
`@@ -16,14 +16,15 @@`
`16`	`16`	`* #id`
`17`	`17`	`*`
`18`	`18`	`* @author acdcjunior`
	`19`	`+ *`
`19`	`20`	`* @since 0.9.0`
`20`	`21`	`*/`
`21`	`22`	`public class IdAttributeCssSelector implements CssConditionalSelector<AttributeCondition> {`
`22`	`23`
`23`	`24`	`private static final String ID_ATTRIBUTE = "id";`
`24`	`25`
`25`	`26`	`/**`
`26`		`- * @see {@link org.w3c.css.sac.Condition#SAC_ID_CONDITION}`
	`27`	`+ * see {@link org.w3c.css.sac.Condition#SAC_ID_CONDITION}`
`27`	`28`	`*`
`28`	`29`	`* This condition checks an id attribute. Example:`
`29`	`30`	`*`
Original file line number	Diff line number	Diff line change
`@@ -17,9 +17,10 @@`
`17`	`17`	`/**`
`18`	`18`	`* E.firstCondition.secondCondition`
`19`	`19`	`*`
`20`		`- * @see {@link Condition#SAC_AND_CONDITION}`
	`20`	`+ * see {@link Condition#SAC_AND_CONDITION}`
`21`	`21`	`*`
`22`	`22`	`* @author acdcjunior`
	`23`	`+ *`
`23`	`24`	`* @since 0.9.0`
`24`	`25`	`*/`
`25`	`26`	`public class AndConditionalCssSelector implements CssConditionalSelector<CombinatorCondition> {`
Original file line number	Diff line number	Diff line change
`@@ -4,6 +4,7 @@`
`4`	`4`	`* http://api.jquery.com/file-selector/`
`5`	`5`	`*`
`6`	`6`	`* @since 0.9.0`
	`7`	`+ *`
`7`	`8`	`* @author acdcjunior`
`8`	`9`	`*/`
`9`	`10`	`public class FilePseudoClass extends InputTypeAttributePseudoClass {`