endsWithIgnoringCase(java.lang.String suffix) {
return org.hamcrest.core.StringEndsWith.endsWithIgnoringCase(suffix);
}
diff --git a/hamcrest/src/main/java/org/hamcrest/CustomMatcher.java b/hamcrest/src/main/java/org/hamcrest/CustomMatcher.java
index 3b5006e77..0a63c8b27 100644
--- a/hamcrest/src/main/java/org/hamcrest/CustomMatcher.java
+++ b/hamcrest/src/main/java/org/hamcrest/CustomMatcher.java
@@ -13,17 +13,21 @@
*
* This class is designed for scenarios where an anonymous inner class
* matcher makes sense. It should not be used by API designers implementing
- * matchers.
+ * matchers. See {@link CustomTypeSafeMatcher} for a type safe variant of
+ * this class that you probably want to use.
*
* @author Neil Dunn
- * @see CustomTypeSafeMatcher for a type safe variant of this class that you probably
- * want to use.
* @param The type of object being matched.
+ * @see CustomTypeSafeMatcher
*/
public abstract class CustomMatcher extends BaseMatcher {
private final String fixedDescription;
+ /**
+ * Constructor
+ * @param description the description of this matcher
+ */
public CustomMatcher(String description) {
if (description == null) {
throw new IllegalArgumentException("Description should be non null!");
diff --git a/hamcrest/src/main/java/org/hamcrest/CustomTypeSafeMatcher.java b/hamcrest/src/main/java/org/hamcrest/CustomTypeSafeMatcher.java
index 3becc146e..3aff0d2e0 100644
--- a/hamcrest/src/main/java/org/hamcrest/CustomTypeSafeMatcher.java
+++ b/hamcrest/src/main/java/org/hamcrest/CustomTypeSafeMatcher.java
@@ -1,7 +1,7 @@
package org.hamcrest;
/**
- * Utility class for writing one off matchers.
+ * Utility class for writing one off matchers (with type safety and null checks).
* For example:
*
* Matcher<String> aNonEmptyString = new CustomTypeSafeMatcher<String>("a non empty string") {
@@ -24,6 +24,10 @@ public abstract class CustomTypeSafeMatcher extends TypeSafeMatcher {
private final String fixedDescription;
+ /**
+ * Constructor
+ * @param description the description of this matcher
+ */
public CustomTypeSafeMatcher(String description) {
if (description == null) {
throw new IllegalArgumentException("Description must be non null!");
diff --git a/hamcrest/src/main/java/org/hamcrest/Description.java b/hamcrest/src/main/java/org/hamcrest/Description.java
index cd9b86151..31031742d 100644
--- a/hamcrest/src/main/java/org/hamcrest/Description.java
+++ b/hamcrest/src/main/java/org/hamcrest/Description.java
@@ -8,16 +8,16 @@
*/
public interface Description {
- /**
- * A description that consumes input but does nothing.
- */
- static final Description NONE = new NullDescription();
+ /**
+ * A description that consumes input but does nothing, implemented by
+ * {@link NullDescription}.
+ */
+ Description NONE = new NullDescription();
/**
* Appends some plain text to the description.
*
- * @param text
- * the text to append.
+ * @param text the text to append.
* @return the update description when displaying the matcher error.
*/
Description appendText(String text);
@@ -25,8 +25,7 @@ public interface Description {
/**
* Appends the description of a {@link SelfDescribing} value to this description.
*
- * @param value
- * the value to append.
+ * @param value the value to append.
* @return the update description when displaying the matcher error.
*/
Description appendDescriptionOf(SelfDescribing value);
@@ -34,8 +33,7 @@ public interface Description {
/**
* Appends an arbitrary value to the description.
*
- * @param value
- * the object to append.
+ * @param value the object to append.
* @return the update description when displaying the matcher error.
*/
Description appendValue(Object value);
@@ -43,16 +41,11 @@ public interface Description {
/**
* Appends a list of values to the description.
*
- * @param
- * the description type.
- * @param start
- * the prefix.
- * @param separator
- * the separator.
- * @param end
- * the suffix.
- * @param values
- * the values to append.
+ * @param the description type.
+ * @param start the prefix.
+ * @param separator the separator.
+ * @param end the suffix.
+ * @param values the values to append.
* @return the update description when displaying the matcher error.
*/
Description appendValueList(String start, String separator, String end,
@@ -61,16 +54,11 @@ Description appendValueList(String start, String separator, String end,
/**
* Appends a list of values to the description.
*
- * @param
- * the description type.
- * @param start
- * the prefix.
- * @param separator
- * the separator.
- * @param end
- * the suffix.
- * @param values
- * the values to append.
+ * @param the description type.
+ * @param start the prefix.
+ * @param separator the separator.
+ * @param end the suffix.
+ * @param values the values to append.
* @return the update description when displaying the matcher error.
*/
Description appendValueList(String start, String separator, String end,
@@ -79,56 +67,62 @@ Description appendValueList(String start, String separator, String end,
/**
* Appends a list of {@link org.hamcrest.SelfDescribing} objects
* to the description.
- * @param start
- * the prefix.
- * @param separator
- * the separator.
- * @param end
- * the suffix.
- * @param values
- * the values to append.
+ *
+ * @param start the prefix.
+ * @param separator the separator.
+ * @param end the suffix.
+ * @param values the values to append.
* @return the update description when displaying the matcher error.
*/
Description appendList(String start, String separator, String end,
Iterable values);
- public static final class NullDescription implements Description {
- @Override
- public Description appendDescriptionOf(SelfDescribing value) {
- return this;
- }
-
- @Override
- public Description appendList(String start, String separator,
- String end, Iterable values) {
- return this;
- }
-
- @Override
- public Description appendText(String text) {
- return this;
- }
-
- @Override
- public Description appendValue(Object value) {
- return this;
- }
-
- @Override
- public Description appendValueList(String start, String separator,
- String end, T... values) {
- return this;
- }
-
- @Override
- public Description appendValueList(String start, String separator,
- String end, Iterable values) {
- return this;
- }
-
- @Override
+ /**
+ * A description that consumes input but does nothing.
+ */
+ final class NullDescription implements Description {
+ /**
+ * Constructor.
+ */
+ public NullDescription() {
+ }
+
+ @Override
+ public Description appendDescriptionOf(SelfDescribing value) {
+ return this;
+ }
+
+ @Override
+ public Description appendList(String start, String separator,
+ String end, Iterable values) {
+ return this;
+ }
+
+ @Override
+ public Description appendText(String text) {
+ return this;
+ }
+
+ @Override
+ public Description appendValue(Object value) {
+ return this;
+ }
+
+ @Override
+ public Description appendValueList(String start, String separator,
+ String end, T... values) {
+ return this;
+ }
+
+ @Override
+ public Description appendValueList(String start, String separator,
+ String end, Iterable values) {
+ return this;
+ }
+
+ @Override
public String toString() {
- return "";
+ return "";
}
}
diff --git a/hamcrest/src/main/java/org/hamcrest/DiagnosingMatcher.java b/hamcrest/src/main/java/org/hamcrest/DiagnosingMatcher.java
index 54e9bf146..44a36c486 100644
--- a/hamcrest/src/main/java/org/hamcrest/DiagnosingMatcher.java
+++ b/hamcrest/src/main/java/org/hamcrest/DiagnosingMatcher.java
@@ -1,12 +1,25 @@
package org.hamcrest;
/**
- * TODO(ngd): Document.
+ * Convenient base class for Matchers of a specific type and that will report why the
+ * received value has been rejected.
+ *
+ * Unlike the {@link TypeSafeDiagnosingMatcher}, this does not implement the null check
+ * or validate the type, so subclasses need to be prepared to handle these conditions.
+ *
+ * To use, implement {@link #matches(Object, Description)}
*
* @param the type of matcher being diagnosed.
+ * @see TypeSafeDiagnosingMatcher
*/
public abstract class DiagnosingMatcher extends BaseMatcher {
+ /**
+ * Constructor
+ */
+ public DiagnosingMatcher() {
+ }
+
@Override
public final boolean matches(Object item) {
return matches(item, Description.NONE);
@@ -17,6 +30,12 @@ public final void describeMismatch(Object item, Description mismatchDescription)
matches(item, mismatchDescription);
}
+ /**
+ * Evaluates the matcher for argument item .
+ * @param item the value to check
+ * @param mismatchDescription the description for the matcher
+ * @return true if item matches, otherwise false.
+ */
protected abstract boolean matches(Object item, Description mismatchDescription);
}
diff --git a/hamcrest/src/main/java/org/hamcrest/Matcher.java b/hamcrest/src/main/java/org/hamcrest/Matcher.java
index dffc09abe..697009369 100644
--- a/hamcrest/src/main/java/org/hamcrest/Matcher.java
+++ b/hamcrest/src/main/java/org/hamcrest/Matcher.java
@@ -21,6 +21,7 @@
* N.B. Well designed matchers should be immutable.
*
*
+ * @param the matched value type
* @see BaseMatcher
*/
public interface Matcher extends SelfDescribing {
diff --git a/hamcrest/src/main/java/org/hamcrest/MatcherAssert.java b/hamcrest/src/main/java/org/hamcrest/MatcherAssert.java
index c8bd9a505..574f4f61b 100644
--- a/hamcrest/src/main/java/org/hamcrest/MatcherAssert.java
+++ b/hamcrest/src/main/java/org/hamcrest/MatcherAssert.java
@@ -1,11 +1,31 @@
package org.hamcrest;
+/**
+ * The Hamcrest entrypoint, static methods to check if matchers match a
+ * given value.
+ */
public class MatcherAssert {
+ private MatcherAssert() {
+ }
+
+ /**
+ * Checks that a value matches a matcher
+ * @param actual the value to check
+ * @param matcher the matcher
+ * @param the type of the value
+ */
public static void assertThat(T actual, Matcher matcher) {
assertThat("", actual, matcher);
}
+ /**
+ * Checks that a value matches a matcher
+ * @param reason a description of what is being matched
+ * @param actual the value to check
+ * @param matcher the matcher
+ * @param the type of the value
+ */
public static void assertThat(String reason, T actual, Matcher matcher) {
if (!matcher.matches(actual)) {
Description description = new StringDescription();
@@ -21,6 +41,11 @@ public static void assertThat(String reason, T actual, Matcher ma
}
}
+ /**
+ * Checks that an assertion is true
+ * @param reason a description of what is being checked
+ * @param assertion the result of the check
+ */
public static void assertThat(String reason, boolean assertion) {
if (!assertion) {
throw new AssertionError(reason);
diff --git a/hamcrest/src/main/java/org/hamcrest/Matchers.java b/hamcrest/src/main/java/org/hamcrest/Matchers.java
index 38907b1bd..85348ea04 100644
--- a/hamcrest/src/main/java/org/hamcrest/Matchers.java
+++ b/hamcrest/src/main/java/org/hamcrest/Matchers.java
@@ -7,9 +7,20 @@
import java.util.regex.Pattern;
+/**
+ * Builder methods for various matchers.
+ *
+ * Matchers provides syntactic sugar for building matchers, or
+ * chains of matchers. By using static imports on these methods, concise and
+ * readable code calling the matchers can be maintained.
+ *
+ */
@SuppressWarnings({"unused", "WeakerAccess"})
public class Matchers {
+ private Matchers() {
+ }
+
/**
* Creates a matcher that matches if the examined object matches ALL of the specified matchers.
* For example:
@@ -541,7 +552,7 @@ public static org.hamcrest.Matcher equalToObject(java.lang.Obj
/**
* Creates a matcher that matches when the examined object is an instance of the specified type,
* as determined by calling the {@link java.lang.Class#isInstance(Object)} method on that type, passing the
- * the examined object.
+ * examined object.
*
* The created matcher forces a relationship between specified type and the examined object, and should be
* used when it is necessary to make generics conform, for example in the JMock clause
diff --git a/hamcrest/src/main/java/org/hamcrest/StringDescription.java b/hamcrest/src/main/java/org/hamcrest/StringDescription.java
index 76fd39f8c..a8b3e8032 100644
--- a/hamcrest/src/main/java/org/hamcrest/StringDescription.java
+++ b/hamcrest/src/main/java/org/hamcrest/StringDescription.java
@@ -9,10 +9,17 @@ public class StringDescription extends BaseDescription {
private final Appendable out;
+ /**
+ * Creates a new description.
+ */
public StringDescription() {
this(new StringBuilder());
}
+ /**
+ * Creates a new description using the given appendable.
+ * @param out the place to append the description.
+ */
public StringDescription(Appendable out) {
this.out = out;
}
diff --git a/hamcrest/src/main/java/org/hamcrest/TypeSafeDiagnosingMatcher.java b/hamcrest/src/main/java/org/hamcrest/TypeSafeDiagnosingMatcher.java
index 73edb8354..4bcf871b2 100644
--- a/hamcrest/src/main/java/org/hamcrest/TypeSafeDiagnosingMatcher.java
+++ b/hamcrest/src/main/java/org/hamcrest/TypeSafeDiagnosingMatcher.java
@@ -6,10 +6,11 @@
* Convenient base class for Matchers that require a non-null value of a specific type
* and that will report why the received value has been rejected.
* This implements the null check, checks the type and then casts.
- * To use, implement
matchesSafely() .
+ * To use, implement {@link #matchesSafely(Object, Description)}.
+ *
+ * @param the matcher type.
+ * @see DiagnosingMatcher
*
- * @param
- * the matcher type.
* @author Neil Dunn
* @author Nat Pryce
* @author Steve Freeman
diff --git a/hamcrest/src/main/java/org/hamcrest/TypeSafeMatcher.java b/hamcrest/src/main/java/org/hamcrest/TypeSafeMatcher.java
index d7f057b6e..4bad8e8a4 100644
--- a/hamcrest/src/main/java/org/hamcrest/TypeSafeMatcher.java
+++ b/hamcrest/src/main/java/org/hamcrest/TypeSafeMatcher.java
@@ -45,18 +45,17 @@ protected TypeSafeMatcher(ReflectiveTypeFinder typeFinder) {
}
/**
- * Subclasses should implement this. The item will already have been checked for
- * the specific type and will never be null.
+ * Check if the item matches. The item will already have been checked for
+ * the specific type and will never be null. Subclasses should implement this.
*
- * @param item
- * the type safe item to match against.
+ * @param item the type safe item to match against.
* @return boolean true/false depending if item matches matcher.
*/
protected abstract boolean matchesSafely(T item);
/**
- * Subclasses should override this. The item will already have been checked for
- * the specific type and will never be null.
+ * Describe the mismatch. The item will already have been checked for
+ * the specific type and will never be null. Subclasses should override this.
*
* @param item
* the type safe item to match against.
diff --git a/hamcrest/src/main/java/org/hamcrest/beans/HasProperty.java b/hamcrest/src/main/java/org/hamcrest/beans/HasProperty.java
index 8ddd0f880..cce9a8b3c 100644
--- a/hamcrest/src/main/java/org/hamcrest/beans/HasProperty.java
+++ b/hamcrest/src/main/java/org/hamcrest/beans/HasProperty.java
@@ -3,12 +3,14 @@
import org.hamcrest.Description;
import org.hamcrest.Matcher;
import org.hamcrest.TypeSafeMatcher;
+import org.hamcrest.collection.ArrayMatching;
/**
- * A Matcher that checks that an object has a JavaBean property
- * with the specified name. If an error occurs during introspection
- * of the object then this is treated as a mismatch.
+ * A matcher that checks if an object has a JavaBean property with the
+ * specified name. If an error occurs during introspection of the object
+ * then this is treated as a mismatch.
*
+ * @param The Matcher type.
* @author Iain McGinniss
* @author Nat Pryce
* @author Steve Freeman
@@ -17,6 +19,11 @@ public class HasProperty extends TypeSafeMatcher {
private final String propertyName;
+ /**
+ * Constructor, best called from {@link #hasProperty(String)}.
+ * @param propertyName the name of the property
+ * @see #hasProperty(String)
+ */
public HasProperty(String propertyName) {
this.propertyName = propertyName;
}
diff --git a/hamcrest/src/main/java/org/hamcrest/beans/HasPropertyWithValue.java b/hamcrest/src/main/java/org/hamcrest/beans/HasPropertyWithValue.java
index 7c3de8a88..a734f8000 100644
--- a/hamcrest/src/main/java/org/hamcrest/beans/HasPropertyWithValue.java
+++ b/hamcrest/src/main/java/org/hamcrest/beans/HasPropertyWithValue.java
@@ -17,9 +17,9 @@
import static org.hamcrest.beans.PropertyUtil.NO_ARGUMENTS;
/**
- * Matcher that asserts that a JavaBean property on an argument passed to the
- * mock object meets the provided matcher. This is useful for when objects
- * are created within code under test and passed to a mock object, and you wish
+ *
A matcher that checks if an object has a JavaBean property with the
+ * specified name and an expected value. This is useful for when objects are
+ * created within code under test and passed to a mock object, and you wish
* to assert that the created object has certain properties.
*
*
@@ -27,8 +27,7 @@
* Consider the situation where we have a class representing a person, which
* follows the basic JavaBean convention of having get() and possibly set()
* methods for it's properties:
- *
- * public class Person {
+ * {@code public class Person {
* private String name;
* public Person(String person) {
* this.person = person;
@@ -36,22 +35,20 @@
* public String getName() {
* return name;
* }
- * }
+ * } }
*
* And that these person objects are generated within a piece of code under test
* (a class named PersonGenerator). This object is sent to one of our mock objects
* which overrides the PersonGenerationListener interface:
- *
- * public interface PersonGenerationListener {
+ * {@code public interface PersonGenerationListener {
* public void personGenerated(Person person);
- * }
+ * } }
*
* In order to check that the code under test generates a person with name
* "Iain" we would do the following:
- *
- * Mock personGenListenerMock = mock(PersonGenerationListener.class);
+ * {@code Mock personGenListenerMock = mock(PersonGenerationListener.class);
* personGenListenerMock.expects(once()).method("personGenerated").with(and(isA(Person.class), hasProperty("Name", eq("Iain")));
- * PersonGenerationListener listener = (PersonGenerationListener)personGenListenerMock.proxy();
+ * PersonGenerationListener listener = (PersonGenerationListener)personGenListenerMock.proxy(); }
*
* If an exception is thrown by the getter method for a property, the property
* does not exist, is not readable, or a reflection related exception is thrown
@@ -59,11 +56,12 @@
* the matches method will return false.
*
* This matcher class will also work with JavaBean objects that have explicit
- * bean descriptions via an associated BeanInfo description class. See the
- * JavaBeans specification for more information:
- * http://java.sun.com/products/javabeans/docs/index.html
+ * bean descriptions via an associated BeanInfo description class.
+ * See https://docs.oracle.com/javase/8/docs/technotes/guides/beans/index.html for
+ * more information on JavaBeans.
*
*
+ * @param the Matcher type
* @author Iain McGinniss
* @author Nat Pryce
* @author Steve Freeman
@@ -76,10 +74,23 @@ public class HasPropertyWithValue extends TypeSafeDiagnosingMatcher {
private final Matcher valueMatcher;
private final String messageFormat;
+ /**
+ * Constructor, best called from {@link #hasProperty(String, Matcher)} or
+ * {@link #hasPropertyAtPath(String, Matcher)}.
+ * @param propertyName the name of the property
+ * @param valueMatcher matcher for the expected value
+ */
public HasPropertyWithValue(String propertyName, Matcher valueMatcher) {
this(propertyName, valueMatcher, " property '%s' ");
}
+ /**
+ * Constructor, best called from {@link #hasProperty(String, Matcher)} or
+ * {@link #hasPropertyAtPath(String, Matcher)}.
+ * @param propertyName the name of the property
+ * @param valueMatcher matcher for the expected value
+ * @param messageFormat format string for the description
+ */
public HasPropertyWithValue(String propertyName, Matcher valueMatcher, String messageFormat) {
this.propertyName = propertyName;
this.valueMatcher = nastyGenericsWorkaround(valueMatcher);
diff --git a/hamcrest/src/main/java/org/hamcrest/beans/PropertyUtil.java b/hamcrest/src/main/java/org/hamcrest/beans/PropertyUtil.java
index 79a51298b..71b7dceae 100644
--- a/hamcrest/src/main/java/org/hamcrest/beans/PropertyUtil.java
+++ b/hamcrest/src/main/java/org/hamcrest/beans/PropertyUtil.java
@@ -5,8 +5,8 @@
import java.beans.PropertyDescriptor;
/**
- * Utility class for accessing properties on JavaBean objects.
- * See http://java.sun.com/products/javabeans/docs/index.html for
+ * Utility class with static methods for accessing properties on JavaBean objects.
+ * See https://docs.oracle.com/javase/8/docs/technotes/guides/beans/index.html for
* more information on JavaBeans.
*
* @author Iain McGinniss
@@ -15,6 +15,9 @@
*/
public class PropertyUtil {
+ private PropertyUtil() {
+ }
+
/**
* Returns the description of the property with the provided
* name on the provided object's interface.
@@ -52,6 +55,9 @@ public static PropertyDescriptor[] propertyDescriptorsFor(Object fromObj, Class<
}
}
+ /**
+ * Empty object array, used for documenting that we are deliberately passing no arguments to a method.
+ */
public static final Object[] NO_ARGUMENTS = new Object[0];
}
diff --git a/hamcrest/src/main/java/org/hamcrest/beans/SamePropertyValuesAs.java b/hamcrest/src/main/java/org/hamcrest/beans/SamePropertyValuesAs.java
index 3928647b6..94f4dba15 100644
--- a/hamcrest/src/main/java/org/hamcrest/beans/SamePropertyValuesAs.java
+++ b/hamcrest/src/main/java/org/hamcrest/beans/SamePropertyValuesAs.java
@@ -13,6 +13,12 @@
import static org.hamcrest.beans.PropertyUtil.propertyDescriptorsFor;
import static org.hamcrest.core.IsEqual.equalTo;
+/**
+ * A matcher that checks if a given bean has the same property values
+ * as an example bean.
+ * @param the matcher value type.
+ * @see #samePropertyValuesAs(Object, String...)
+ */
public class SamePropertyValuesAs extends DiagnosingMatcher {
private final T expectedBean;
@@ -20,6 +26,11 @@ public class SamePropertyValuesAs extends DiagnosingMatcher {
private final List propertyMatchers;
private final List ignoredFields;
+ /**
+ * Constructor, best called from {@link #samePropertyValuesAs(Object, String...)}.
+ * @param expectedBean the bean object with the expected values
+ * @param ignoredProperties list of property names that should be excluded from the match
+ */
@SuppressWarnings("WeakerAccess")
public SamePropertyValuesAs(T expectedBean, List ignoredProperties) {
PropertyDescriptor[] descriptors = propertyDescriptorsFor(expectedBean, Object.class);
@@ -138,21 +149,22 @@ private static Object readProperty(Method method, Object target) {
}
/**
- * Creates a matcher that matches when the examined object has values for all of
+ * Creates a matcher that matches when the examined object has values for all of
* its JavaBean properties that are equal to the corresponding values of the
* specified bean. If any properties are marked as ignored, they will be dropped from
* both the expected and actual bean. Note that the ignored properties use JavaBean
- * display names, for example
age rather than method names such as getAge .
+ * display names, for example "age" rather than method names such as
+ * "getAge".
+ *
* For example:
- * assertThat(myBean, samePropertyValuesAs(myExpectedBean))
- * assertThat(myBean, samePropertyValuesAs(myExpectedBean), "age", "height")
+ * {@code
+ * assertThat(myBean, samePropertyValuesAs(myExpectedBean))
+ * assertThat(myBean, samePropertyValuesAs(myExpectedBean), "age", "height")
+ * }
*
- * @param
- * the matcher type.
- * @param expectedBean
- * the bean against which examined beans are compared
- * @param ignoredProperties
- * do not check any of these named properties.
+ * @param the matcher value type.
+ * @param expectedBean the bean against which examined beans are compared
+ * @param ignoredProperties do not check any of these named properties.
* @return The matcher.
*/
public static Matcher samePropertyValuesAs(B expectedBean, String... ignoredProperties) {
diff --git a/hamcrest/src/main/java/org/hamcrest/beans/package-info.java b/hamcrest/src/main/java/org/hamcrest/beans/package-info.java
new file mode 100644
index 000000000..d122dc661
--- /dev/null
+++ b/hamcrest/src/main/java/org/hamcrest/beans/package-info.java
@@ -0,0 +1,4 @@
+/**
+ * Matchers of Java Bean properties and their values.
+ */
+package org.hamcrest.beans;
\ No newline at end of file
diff --git a/hamcrest/src/main/java/org/hamcrest/beans/package.html b/hamcrest/src/main/java/org/hamcrest/beans/package.html
deleted file mode 100644
index 0dcc555d3..000000000
--- a/hamcrest/src/main/java/org/hamcrest/beans/package.html
+++ /dev/null
@@ -1,7 +0,0 @@
-
-
-
-
- Matchers of Java Bean properties and their values.
-
-
diff --git a/hamcrest/src/main/java/org/hamcrest/collection/ArrayAsIterableMatcher.java b/hamcrest/src/main/java/org/hamcrest/collection/ArrayAsIterableMatcher.java
index f6328bfad..5ea3e2d3e 100644
--- a/hamcrest/src/main/java/org/hamcrest/collection/ArrayAsIterableMatcher.java
+++ b/hamcrest/src/main/java/org/hamcrest/collection/ArrayAsIterableMatcher.java
@@ -10,14 +10,34 @@
import static java.util.Arrays.asList;
/**
+ * A matcher for arrays that matches when each item in the examined array satisfies the
+ * corresponding matcher in the specified list of matchers.
+ *
+ * @param the collection element type
* @author Steve Freeman 2016 http://www.hamcrest.com
*/
public class ArrayAsIterableMatcher extends TypeSafeMatcher {
+ /**
+ * The matchers to match iterable against
+ */
protected final TypeSafeDiagnosingMatcher> iterableMatcher;
+
private final String message;
+
+ /**
+ * The matchers to match items against
+ */
protected final Collection> matchers;
+
+ /**
+ * Constructor, best called from {@link ArrayMatching#arrayContainingInAnyOrder(Matcher[])}.
+ * @param iterableMatcher the iterable matchers
+ * @param matchers the matchers
+ * @param message the description of this matcher
+ * @see ArrayMatching#arrayContainingInAnyOrder(Matcher[])
+ */
public ArrayAsIterableMatcher(
TypeSafeDiagnosingMatcher> iterableMatcher,
Collection> matchers,
diff --git a/hamcrest/src/main/java/org/hamcrest/collection/ArrayMatching.java b/hamcrest/src/main/java/org/hamcrest/collection/ArrayMatching.java
index 86805ae1f..f160ce7be 100644
--- a/hamcrest/src/main/java/org/hamcrest/collection/ArrayMatching.java
+++ b/hamcrest/src/main/java/org/hamcrest/collection/ArrayMatching.java
@@ -11,10 +11,13 @@
import static org.hamcrest.core.IsEqual.equalTo;
/**
- * @author Steve Freeman 2016 http://www.hamcrest.com
* Collected helper code for converting matchers between lists and iterables.
+ *
+ * @author Steve Freeman 2016 http://www.hamcrest.com
*/
public class ArrayMatching {
+ private ArrayMatching() {
+ }
/**
* Creates a matcher for arrays that matches when the examined array contains at least one item
@@ -187,6 +190,12 @@ public static Matcher arrayContaining(List> itemMatc
return new ArrayAsIterableMatcher<>(new IsIterableContainingInOrder<>(itemMatchers), itemMatchers, "");
}
+ /**
+ * Converts item array to corresponding array of equalTo matchers
+ * @param items items to convert
+ * @return list of corresponding equaTo matchers
+ * @param type of array items
+ */
public static List> asEqualMatchers(E[] items) {
final List> matchers = new ArrayList<>();
for (E item : items) {
diff --git a/hamcrest/src/main/java/org/hamcrest/collection/HasItemInArray.java b/hamcrest/src/main/java/org/hamcrest/collection/HasItemInArray.java
index 538d56ad6..102565b75 100644
--- a/hamcrest/src/main/java/org/hamcrest/collection/HasItemInArray.java
+++ b/hamcrest/src/main/java/org/hamcrest/collection/HasItemInArray.java
@@ -10,12 +10,19 @@
/**
* Matches if an array contains an item satisfying a nested matcher.
+ *
+ * @param the array element type
*/
public class HasItemInArray extends TypeSafeMatcher {
private final Matcher elementMatcher;
private final TypeSafeDiagnosingMatcher> collectionMatcher;
+ /**
+ * Constructor, best called from {@link ArrayMatching}.
+ * @param elementMatcher matcher for the expected item
+ * @see ArrayMatching#hasItemInArray(Matcher)
+ */
public HasItemInArray(Matcher elementMatcher) {
this.elementMatcher = elementMatcher;
this.collectionMatcher = new IsIterableContaining<>(elementMatcher);
diff --git a/hamcrest/src/main/java/org/hamcrest/collection/IsArray.java b/hamcrest/src/main/java/org/hamcrest/collection/IsArray.java
index 181bcbebb..fb123bd39 100644
--- a/hamcrest/src/main/java/org/hamcrest/collection/IsArray.java
+++ b/hamcrest/src/main/java/org/hamcrest/collection/IsArray.java
@@ -9,11 +9,17 @@
/**
* Matcher for array whose elements satisfy a sequence of matchers.
* The array size must equal the number of element matchers.
+ *
+ * @param the array element type
*/
public class IsArray extends TypeSafeMatcher {
private final Matcher[] elementMatchers;
+ /**
+ * Constructor, best called from {@link #array(Matcher[])}.
+ * @param elementMatchers matchers for expected values
+ */
public IsArray(Matcher[] elementMatchers) {
this.elementMatchers = elementMatchers.clone();
}
diff --git a/hamcrest/src/main/java/org/hamcrest/collection/IsArrayContainingInAnyOrder.java b/hamcrest/src/main/java/org/hamcrest/collection/IsArrayContainingInAnyOrder.java
index 93490de36..82b4b59ce 100644
--- a/hamcrest/src/main/java/org/hamcrest/collection/IsArrayContainingInAnyOrder.java
+++ b/hamcrest/src/main/java/org/hamcrest/collection/IsArrayContainingInAnyOrder.java
@@ -12,6 +12,7 @@
import static org.hamcrest.core.IsEqual.equalTo;
/**
+ * @param the collection element type
* @deprecated As of release 2.1, replaced by {@link ArrayMatching}.
*/
@Deprecated
@@ -20,6 +21,11 @@ public class IsArrayContainingInAnyOrder extends TypeSafeMatcher {
private final IsIterableContainingInAnyOrder iterableMatcher;
private final Collection> matchers;
+ /**
+ * Constructor, best called from {@link #arrayContainingInAnyOrder(Object[])},
+ * {@link #arrayContainingInAnyOrder(Matcher[])}, or {@link #arrayContainingInAnyOrder(Collection)}.
+ * @param matchers matchers for expected values
+ */
public IsArrayContainingInAnyOrder(Collection> matchers) {
this.iterableMatcher = new IsIterableContainingInAnyOrder<>(matchers);
this.matchers = matchers;
diff --git a/hamcrest/src/main/java/org/hamcrest/collection/IsArrayContainingInOrder.java b/hamcrest/src/main/java/org/hamcrest/collection/IsArrayContainingInOrder.java
index 291ed1db5..3c748cfbe 100644
--- a/hamcrest/src/main/java/org/hamcrest/collection/IsArrayContainingInOrder.java
+++ b/hamcrest/src/main/java/org/hamcrest/collection/IsArrayContainingInOrder.java
@@ -12,6 +12,8 @@
import static org.hamcrest.core.IsEqual.equalTo;
/**
+ * @param the array element type
+ *
* @deprecated As of release 2.1, replaced by {@link ArrayMatching}.
*/
public class IsArrayContainingInOrder extends TypeSafeMatcher {
@@ -19,6 +21,11 @@ public class IsArrayContainingInOrder extends TypeSafeMatcher {
private final Collection> matchers;
private final IsIterableContainingInOrder iterableMatcher;
+ /**
+ * Constructor, best called from {@link #arrayContaining(Object[])},
+ * {@link #arrayContaining(Matcher[])}, or {@link #arrayContaining(List)}.
+ * @param matchers matchers for expected values
+ */
public IsArrayContainingInOrder(List> matchers) {
this.iterableMatcher = new IsIterableContainingInOrder<>(matchers);
this.matchers = matchers;
diff --git a/hamcrest/src/main/java/org/hamcrest/collection/IsArrayWithSize.java b/hamcrest/src/main/java/org/hamcrest/collection/IsArrayWithSize.java
index c0814cc04..9c2dbb85c 100644
--- a/hamcrest/src/main/java/org/hamcrest/collection/IsArrayWithSize.java
+++ b/hamcrest/src/main/java/org/hamcrest/collection/IsArrayWithSize.java
@@ -7,10 +7,17 @@
import static org.hamcrest.core.IsEqual.equalTo;
/**
- * Matches if array size satisfies a nested matcher.
+ * Matches if array size satisfies a size matcher.
+ *
+ * @param the array element type
*/
public class IsArrayWithSize extends FeatureMatcher {
+ /**
+ * Constructor, best called from {@link #emptyArray()},
+ * {@link #arrayWithSize(int)} or {@link #arrayWithSize(Matcher)}.
+ * @param sizeMatcher the expected size
+ */
public IsArrayWithSize(Matcher sizeMatcher) {
super(sizeMatcher, "an array with size","array size");
}
diff --git a/hamcrest/src/main/java/org/hamcrest/collection/IsCollectionWithSize.java b/hamcrest/src/main/java/org/hamcrest/collection/IsCollectionWithSize.java
index 81c5fc61d..ce403a7d7 100644
--- a/hamcrest/src/main/java/org/hamcrest/collection/IsCollectionWithSize.java
+++ b/hamcrest/src/main/java/org/hamcrest/collection/IsCollectionWithSize.java
@@ -9,9 +9,15 @@
/**
* Matches if collection size satisfies a nested matcher.
+ *
+ * @param the collection element type
*/
public class IsCollectionWithSize extends FeatureMatcher, Integer> {
+ /**
+ * Constructor, best called from {@link #hasSize(int)} or {@link #hasSize(Matcher)}.
+ * @param sizeMatcher the expected size
+ */
public IsCollectionWithSize(Matcher sizeMatcher) {
super(sizeMatcher, "a collection with size", "collection size");
}
diff --git a/hamcrest/src/main/java/org/hamcrest/collection/IsEmptyCollection.java b/hamcrest/src/main/java/org/hamcrest/collection/IsEmptyCollection.java
index 25e6da2cc..9109d31cb 100644
--- a/hamcrest/src/main/java/org/hamcrest/collection/IsEmptyCollection.java
+++ b/hamcrest/src/main/java/org/hamcrest/collection/IsEmptyCollection.java
@@ -7,10 +7,19 @@
import java.util.Collection;
/**
- * Tests if collection is empty.
+ * Tests if a collection is empty.
+ *
+ * @param the collection element type
*/
public class IsEmptyCollection extends TypeSafeMatcher> {
+ /**
+ * Constructor, best called from {@link #empty()} or
+ * {@link #emptyCollectionOf(Class)}.
+ */
+ public IsEmptyCollection() {
+ }
+
@Override
public boolean matchesSafely(Collection item) {
return item.isEmpty();
diff --git a/hamcrest/src/main/java/org/hamcrest/collection/IsEmptyIterable.java b/hamcrest/src/main/java/org/hamcrest/collection/IsEmptyIterable.java
index d1dc03946..c5aab514c 100644
--- a/hamcrest/src/main/java/org/hamcrest/collection/IsEmptyIterable.java
+++ b/hamcrest/src/main/java/org/hamcrest/collection/IsEmptyIterable.java
@@ -5,10 +5,19 @@
import org.hamcrest.TypeSafeMatcher;
/**
- * Tests if collection is empty.
+ * Tests if an iterable is empty.
+ *
+ * @param the iterable element type
*/
public class IsEmptyIterable extends TypeSafeMatcher> {
+ /**
+ * Constructor, best called from {@link #emptyIterable()} or
+ * {@link #emptyIterableOf(Class)}.
+ */
+ public IsEmptyIterable() {
+ }
+
@Override
public boolean matchesSafely(Iterable iterable) {
return !iterable.iterator().hasNext();
diff --git a/hamcrest/src/main/java/org/hamcrest/collection/IsIn.java b/hamcrest/src/main/java/org/hamcrest/collection/IsIn.java
index f18c2bd65..2be7b2fc5 100644
--- a/hamcrest/src/main/java/org/hamcrest/collection/IsIn.java
+++ b/hamcrest/src/main/java/org/hamcrest/collection/IsIn.java
@@ -7,14 +7,26 @@
import java.util.Arrays;
import java.util.Collection;
+/**
+ * Tests if a collection contains a matching object.
+ * @param the type of the objects in the collection
+ */
public class IsIn extends BaseMatcher {
private final Collection collection;
+ /**
+ * Constructor, best called from {@link #in(Collection)}.
+ * @param collection the expected element matchers
+ */
public IsIn(Collection collection) {
this.collection = collection;
}
+ /**
+ * Constructor, best called from {@link #in(Object[])}.
+ * @param elements the expected elements
+ */
public IsIn(T[] elements) {
collection = Arrays.asList(elements);
}
diff --git a/hamcrest/src/main/java/org/hamcrest/collection/IsIterableContainingInAnyOrder.java b/hamcrest/src/main/java/org/hamcrest/collection/IsIterableContainingInAnyOrder.java
index 087570cd4..84c744d4b 100644
--- a/hamcrest/src/main/java/org/hamcrest/collection/IsIterableContainingInAnyOrder.java
+++ b/hamcrest/src/main/java/org/hamcrest/collection/IsIterableContainingInAnyOrder.java
@@ -11,10 +11,22 @@
import static org.hamcrest.core.IsEqual.equalTo;
+/**
+ * Tests if an iterable contains matching elements in any order.
+ *
+ * @param the type of items in the iterable.
+ */
public class IsIterableContainingInAnyOrder extends TypeSafeDiagnosingMatcher> {
private final Collection> matchers;
+ /**
+ * Constructor, best called from one of the static "containsInAnyOrder" factory methods.
+ * @param matchers the matchers
+ * @see #containsInAnyOrder(Object[])
+ * @see #containsInAnyOrder(Collection)
+ * @see #containsInAnyOrder(Matcher[])
+ */
public IsIterableContainingInAnyOrder(Collection> matchers) {
this.matchers = matchers;
}
diff --git a/hamcrest/src/main/java/org/hamcrest/collection/IsIterableContainingInOrder.java b/hamcrest/src/main/java/org/hamcrest/collection/IsIterableContainingInOrder.java
index 00b89ea7f..dfb9d1289 100644
--- a/hamcrest/src/main/java/org/hamcrest/collection/IsIterableContainingInOrder.java
+++ b/hamcrest/src/main/java/org/hamcrest/collection/IsIterableContainingInOrder.java
@@ -11,10 +11,24 @@
import static java.util.Collections.singletonList;
import static org.hamcrest.collection.ArrayMatching.asEqualMatchers;
+/**
+ * Tests if an iterable contains matching elements in order.
+ *
+ * @param the type of items in the iterable.
+ */
public class IsIterableContainingInOrder extends TypeSafeDiagnosingMatcher> {
private final List> matchers;
+ /**
+ * Constructor, best called from one of the static "contains" factory methods.
+ * @param matchers the matchers
+ *
+ * @see #contains(Object[])
+ * @see #contains(Matcher)
+ * @see #contains(Matcher[])
+ * @see #contains(List)
+ */
public IsIterableContainingInOrder(List> matchers) {
this.matchers = matchers;
}
diff --git a/hamcrest/src/main/java/org/hamcrest/collection/IsIterableContainingInRelativeOrder.java b/hamcrest/src/main/java/org/hamcrest/collection/IsIterableContainingInRelativeOrder.java
index 6aca721ec..5d39f7527 100644
--- a/hamcrest/src/main/java/org/hamcrest/collection/IsIterableContainingInRelativeOrder.java
+++ b/hamcrest/src/main/java/org/hamcrest/collection/IsIterableContainingInRelativeOrder.java
@@ -10,9 +10,19 @@
import static java.util.Arrays.asList;
import static org.hamcrest.core.IsEqual.equalTo;
+/**
+ * Tests if an iterable contains matching elements in relative order.
+ *
+ * @param the type of items in the iterable.
+ */
public class IsIterableContainingInRelativeOrder extends TypeSafeDiagnosingMatcher> {
private final List> matchers;
+ /**
+ * Constructor, best called from {@link #containsInRelativeOrder(Object[])} ,
+ * {@link #containsInRelativeOrder(Matcher[])}, or {@link #containsInRelativeOrder(List)}.
+ * @param matchers the matchers
+ */
public IsIterableContainingInRelativeOrder(List> matchers) {
this.matchers = matchers;
}
diff --git a/hamcrest/src/main/java/org/hamcrest/collection/IsIterableWithSize.java b/hamcrest/src/main/java/org/hamcrest/collection/IsIterableWithSize.java
index 586dfcef6..ea36fb441 100644
--- a/hamcrest/src/main/java/org/hamcrest/collection/IsIterableWithSize.java
+++ b/hamcrest/src/main/java/org/hamcrest/collection/IsIterableWithSize.java
@@ -7,8 +7,18 @@
import static org.hamcrest.core.IsEqual.equalTo;
+/**
+ * Matches if iterable size satisfies a size matcher.
+ *
+ * @param the iterable element type
+ */
public class IsIterableWithSize extends FeatureMatcher, Integer> {
+ /**
+ * Constructor, best called from {@link #iterableWithSize(int)} or
+ * {@link #iterableWithSize(Matcher)}.
+ * @param sizeMatcher checks the expected size of the iterable
+ */
public IsIterableWithSize(Matcher sizeMatcher) {
super(sizeMatcher, "an iterable with size", "iterable size");
}
diff --git a/hamcrest/src/main/java/org/hamcrest/collection/IsMapContaining.java b/hamcrest/src/main/java/org/hamcrest/collection/IsMapContaining.java
index d81dbd9a5..1c0d38de1 100644
--- a/hamcrest/src/main/java/org/hamcrest/collection/IsMapContaining.java
+++ b/hamcrest/src/main/java/org/hamcrest/collection/IsMapContaining.java
@@ -10,11 +10,28 @@
import static org.hamcrest.core.IsAnything.anything;
import static org.hamcrest.core.IsEqual.equalTo;
+/**
+ * Matches if map keys, values or entries match the value matchers.
+ * @param the type of the map keys
+ * @param the type of the map values
+ */
public class IsMapContaining extends TypeSafeMatcher> {
private final Matcher keyMatcher;
private final Matcher valueMatcher;
+ /**
+ * Constructor, best called from one of the static factory methods (hasKey, hasValue,
+ * or hasEntry).
+ * @param keyMatcher matcher for expected keys
+ * @param valueMatcher matcher for expected values
+ * @see #hasKey(Object)
+ * @see #hasKey(Matcher)
+ * @see #hasValue(Object)
+ * @see #hasValue(Matcher)
+ * @see #hasEntry(Object, Object)
+ * @see #hasEntry(Matcher, Matcher)
+ */
public IsMapContaining(Matcher keyMatcher, Matcher valueMatcher) {
this.keyMatcher = keyMatcher;
this.valueMatcher = valueMatcher;
diff --git a/hamcrest/src/main/java/org/hamcrest/collection/IsMapWithSize.java b/hamcrest/src/main/java/org/hamcrest/collection/IsMapWithSize.java
index b4670c329..cce315b09 100644
--- a/hamcrest/src/main/java/org/hamcrest/collection/IsMapWithSize.java
+++ b/hamcrest/src/main/java/org/hamcrest/collection/IsMapWithSize.java
@@ -9,9 +9,17 @@
/**
* Matches if map size satisfies a nested matcher.
+ *
+ * @param the map key type.
+ * @param the map value type.
*/
public final class IsMapWithSize extends FeatureMatcher, Integer> {
+ /**
+ * Constructor, best called from {@link #aMapWithSize(int)}, {@link #aMapWithSize(Matcher)},
+ * or {@link #anEmptyMap()}.
+ * @param sizeMatcher matcher for the expected size of the map
+ */
@SuppressWarnings("WeakerAccess")
public IsMapWithSize(Matcher sizeMatcher) {
super(sizeMatcher, "a map with size", "map size");
@@ -64,10 +72,8 @@ protected Integer featureValueOf(Map actual) {
* For example:
* assertThat(myMap, is(anEmptyMap()))
*
- * @param
- * the map key type.
- * @param
- * the map value type.
+ * @param the map key type.
+ * @param the map value type.
* @return The matcher.
*/
public static Matcher> anEmptyMap() {
diff --git a/hamcrest/src/main/java/org/hamcrest/collection/package-info.java b/hamcrest/src/main/java/org/hamcrest/collection/package-info.java
new file mode 100644
index 000000000..f0e6d370d
--- /dev/null
+++ b/hamcrest/src/main/java/org/hamcrest/collection/package-info.java
@@ -0,0 +1,4 @@
+/**
+ * Matchers of arrays and collections.
+ */
+package org.hamcrest.collection;
diff --git a/hamcrest/src/main/java/org/hamcrest/collection/package.html b/hamcrest/src/main/java/org/hamcrest/collection/package.html
deleted file mode 100644
index 6248d8da3..000000000
--- a/hamcrest/src/main/java/org/hamcrest/collection/package.html
+++ /dev/null
@@ -1,7 +0,0 @@
-
-
-
-
- Matchers of arrays and collections.
-
-
diff --git a/hamcrest/src/main/java/org/hamcrest/comparator/ComparatorMatcherBuilder.java b/hamcrest/src/main/java/org/hamcrest/comparator/ComparatorMatcherBuilder.java
index 022e519cf..3f0cbc48d 100644
--- a/hamcrest/src/main/java/org/hamcrest/comparator/ComparatorMatcherBuilder.java
+++ b/hamcrest/src/main/java/org/hamcrest/comparator/ComparatorMatcherBuilder.java
@@ -8,6 +8,10 @@
import static java.lang.Integer.signum;
+/**
+ * Builder for matchers that allow matchers to use a corresponding Compartor
+ * @param the type of the value being compared/matched.
+ */
public final class ComparatorMatcherBuilder {
private final Comparator comparator;
diff --git a/hamcrest/src/main/java/org/hamcrest/comparator/package-info.java b/hamcrest/src/main/java/org/hamcrest/comparator/package-info.java
new file mode 100644
index 000000000..6a934c9ce
--- /dev/null
+++ b/hamcrest/src/main/java/org/hamcrest/comparator/package-info.java
@@ -0,0 +1,4 @@
+/**
+ * Helper classes for building matcher comparators.
+ */
+package org.hamcrest.comparator;
\ No newline at end of file
diff --git a/hamcrest/src/main/java/org/hamcrest/core/AllOf.java b/hamcrest/src/main/java/org/hamcrest/core/AllOf.java
index 549f16817..8d43b84a8 100644
--- a/hamcrest/src/main/java/org/hamcrest/core/AllOf.java
+++ b/hamcrest/src/main/java/org/hamcrest/core/AllOf.java
@@ -3,22 +3,35 @@
import org.hamcrest.Description;
import org.hamcrest.DiagnosingMatcher;
import org.hamcrest.Matcher;
+import org.hamcrest.collection.ArrayMatching;
import java.util.Arrays;
/**
* Calculates the logical conjunction of multiple matchers. Evaluation is shortcut, so
* subsequent matchers are not called if an earlier matcher returns false.
+ *
+ * @param the matched value type
*/
public class AllOf extends DiagnosingMatcher {
private final Iterable> matchers;
+ /**
+ * Constructor, best called from {@link #allOf(Matcher[])}.
+ * @param matchers the matchers
+ * @see #allOf(Matcher[])
+ */
@SafeVarargs
public AllOf(Matcher ... matchers) {
this(Arrays.asList(matchers));
}
+ /**
+ * Constructor, best called from {@link #allOf(Iterable)}.
+ * @param matchers the matchers
+ * @see #allOf(Iterable)
+ */
public AllOf(Iterable> matchers) {
this.matchers = matchers;
}
diff --git a/hamcrest/src/main/java/org/hamcrest/core/AnyOf.java b/hamcrest/src/main/java/org/hamcrest/core/AnyOf.java
index 91c664d95..0b08488c6 100644
--- a/hamcrest/src/main/java/org/hamcrest/core/AnyOf.java
+++ b/hamcrest/src/main/java/org/hamcrest/core/AnyOf.java
@@ -2,20 +2,33 @@
import org.hamcrest.Description;
import org.hamcrest.Matcher;
+import org.hamcrest.collection.ArrayMatching;
import java.util.Arrays;
/**
* Calculates the logical disjunction of multiple matchers. Evaluation is shortcut, so
* subsequent matchers are not called if an earlier matcher returns true.
+ *
+ * @param the matched value type
*/
public class AnyOf extends ShortcutCombination {
+ /**
+ * Constructor, best called from {@link #anyOf(Matcher[])}.
+ * @param matchers the matchers
+ * @see #anyOf(Matcher[])
+ */
@SafeVarargs
public AnyOf(Matcher ... matchers) {
this(Arrays.asList(matchers));
}
+ /**
+ * Constructor, best called from {@link #anyOf(Iterable)}.
+ * @param matchers the matchers
+ * @see #anyOf(Iterable)
+ */
public AnyOf(Iterable> matchers) {
super(matchers);
}
diff --git a/hamcrest/src/main/java/org/hamcrest/core/CombinableMatcher.java b/hamcrest/src/main/java/org/hamcrest/core/CombinableMatcher.java
index 52a134aff..f17c9afb6 100644
--- a/hamcrest/src/main/java/org/hamcrest/core/CombinableMatcher.java
+++ b/hamcrest/src/main/java/org/hamcrest/core/CombinableMatcher.java
@@ -7,14 +7,34 @@
import java.util.ArrayList;
/**
- * TODO: Finish Class Level Documentation.
+ * Allows matchers of the same type to be combined using
+ * either/or, or
+ * both/and.
+ *
+ * For example:
+ *
+ * {@code import static org.hamcrest.core.CombinableMatcher.either;
+ * import static org.hamcrest.core.CombinableMatcher.both;
+ * import static org.hamcrest.Matchers.equalTo;
+ * import static org.hamcrest.Matchers.not;
+ *
+ * Matcher either_3_or_4 = either(equalTo(3)).or(equalTo(4));
+ * Matcher neither_3_nor_4 = both(not(equalTo(3))).and(not(equalTo(4)));}
*
* @param the type of matcher being combined.
+ * @see #either(Matcher)
+ * @see #both(Matcher)
*/
public class CombinableMatcher extends TypeSafeDiagnosingMatcher {
private final Matcher matcher;
+ /**
+ * Constructor, best called from either or both.
+ * @param matcher the starting matcher
+ * @see #either(Matcher)
+ * @see #both(Matcher)
+ */
public CombinableMatcher(Matcher matcher) {
this.matcher = matcher;
}
@@ -33,10 +53,20 @@ public void describeTo(Description description) {
description.appendDescriptionOf(matcher);
}
+ /**
+ * Specify the second matcher in a CombinableMatcher pair.
+ * @param other the second matcher
+ * @return the combined matcher
+ */
public CombinableMatcher and(Matcher other) {
return new CombinableMatcher<>(new AllOf<>(templatedListWith(other)));
}
+ /**
+ * Specify the second matcher in a CombinableMatcher pair.
+ * @param other the second matcher
+ * @return the combined matcher
+ */
public CombinableMatcher or(Matcher other) {
return new CombinableMatcher<>(new AnyOf<>(templatedListWith(other)));
}
@@ -53,21 +83,36 @@ private ArrayList> templatedListWith(Matcher other
* For example:
* assertThat("fab", both(containsString("a")).and(containsString("b")))
*
- * @param
- * the matcher type.
- * @param matcher
- * the matcher to combine, and both must pass.
+ * @param the matcher type.
+ * @param matcher the matcher to combine, and both must pass.
* @return The matcher.
*/
public static CombinableBothMatcher both(Matcher matcher) {
return new CombinableBothMatcher<>(matcher);
}
+ /**
+ * Allows syntactic sugar of using both and and.
+ * @param the combined matcher type
+ * @see #both(Matcher)
+ * @see #and(Matcher)
+ */
public static final class CombinableBothMatcher {
private final Matcher first;
+
+ /**
+ * Constructor, best called from {@link #both(Matcher)}.
+ * @param matcher the first matcher
+ */
public CombinableBothMatcher(Matcher matcher) {
this.first = matcher;
}
+
+ /**
+ * Specify the second matcher in a CombinableMatcher pair.
+ * @param other the second matcher
+ * @return the combined matcher
+ */
public CombinableMatcher and(Matcher other) {
return new CombinableMatcher(first).and(other);
}
@@ -78,21 +123,36 @@ public CombinableMatcher and(Matcher other) {
* For example:
* assertThat("fan", either(containsString("a")).or(containsString("b")))
*
- * @param
- * the matcher type.
- * @param matcher
- * the matcher to combine, and either must pass.
+ * @param the matcher type.
+ * @param matcher the matcher to combine, and either must pass.
* @return The matcher.
*/
public static CombinableEitherMatcher either(Matcher matcher) {
return new CombinableEitherMatcher<>(matcher);
}
+ /**
+ * Allows syntactic sugar of using either and or.
+ * @param the combined matcher type
+ * @see #either(Matcher)
+ * @see #or(Matcher)
+ */
public static final class CombinableEitherMatcher {
private final Matcher first;
+
+ /**
+ * Constructor, best called from {@link #either(Matcher)}
+ * @param matcher the matcher
+ */
public CombinableEitherMatcher(Matcher matcher) {
this.first = matcher;
}
+
+ /**
+ * Specify the second matcher in a CombinableMatcher pair.
+ * @param other the second matcher
+ * @return the combined matcher
+ */
public CombinableMatcher or(Matcher other) {
return new CombinableMatcher(first).or(other);
}
diff --git a/hamcrest/src/main/java/org/hamcrest/core/DescribedAs.java b/hamcrest/src/main/java/org/hamcrest/core/DescribedAs.java
index b4138d7f6..c89451e66 100644
--- a/hamcrest/src/main/java/org/hamcrest/core/DescribedAs.java
+++ b/hamcrest/src/main/java/org/hamcrest/core/DescribedAs.java
@@ -10,6 +10,8 @@
/**
* Provides a custom description to another matcher.
+ *
+ * @param the matched value type
*/
public class DescribedAs extends BaseMatcher {
@@ -19,6 +21,12 @@ public class DescribedAs extends BaseMatcher {
private final static Pattern ARG_PATTERN = Pattern.compile("%([0-9]+)");
+ /**
+ * Constructor, best called from {@link #describedAs(String, Matcher, Object...)}.
+ * @param descriptionTemplate the new description for the wrapped matcher
+ * @param matcher the matcher to wrap
+ * @param values optional values to insert into the tokenised description
+ */
public DescribedAs(String descriptionTemplate, Matcher matcher, Object[] values) {
this.descriptionTemplate = descriptionTemplate;
this.matcher = matcher;
@@ -57,18 +65,14 @@ public void describeMismatch(Object item, Description description) {
* For example:
* describedAs("a big decimal equal to %0", equalTo(myBigDecimal), myBigDecimal.toPlainString())
*
- * @param
- * the matcher type.
- * @param description
- * the new description for the wrapped matcher
- * @param matcher
- * the matcher to wrap
- * @param values
- * optional values to insert into the tokenised description
+ * @param the matcher type.
+ * @param descriptionTemplate the new description for the wrapped matcher
+ * @param matcher the matcher to wrap
+ * @param values optional values to insert into the tokenised description
* @return The matcher.
*/
- public static Matcher describedAs(String description, Matcher matcher, Object... values) {
- return new DescribedAs<>(description, matcher, values);
+ public static Matcher describedAs(String descriptionTemplate, Matcher matcher, Object... values) {
+ return new DescribedAs<>(descriptionTemplate, matcher, values);
}
}
diff --git a/hamcrest/src/main/java/org/hamcrest/core/Every.java b/hamcrest/src/main/java/org/hamcrest/core/Every.java
index 6e25fcda9..bf3d809fb 100644
--- a/hamcrest/src/main/java/org/hamcrest/core/Every.java
+++ b/hamcrest/src/main/java/org/hamcrest/core/Every.java
@@ -4,10 +4,19 @@
import org.hamcrest.Matcher;
import org.hamcrest.TypeSafeDiagnosingMatcher;
+/**
+ * A matcher that applies a delegate matcher to every item in an {@link Iterable}.
+ *
+ * @param the type of the items in the iterable
+ */
public class Every extends TypeSafeDiagnosingMatcher> {
private final Matcher matcher;
+ /**
+ * Constructor, best called from {@link #everyItem(Matcher)}.
+ * @param matcher a matcher used to check every item in the iterable.
+ */
public Every(Matcher matcher) {
this.matcher= matcher;
}
diff --git a/hamcrest/src/main/java/org/hamcrest/core/Is.java b/hamcrest/src/main/java/org/hamcrest/core/Is.java
index a23dd73cb..3fc323322 100644
--- a/hamcrest/src/main/java/org/hamcrest/core/Is.java
+++ b/hamcrest/src/main/java/org/hamcrest/core/Is.java
@@ -12,11 +12,17 @@
*
* For example: assertThat(cheese, equalTo(smelly))
* vs. assertThat(cheese, is(equalTo(smelly)))
+ *
+ * @param the matched value type
*/
public class Is extends BaseMatcher {
private final Matcher matcher;
+ /**
+ * Constructor, best called from {@link #is(Object)}, {@link #is(Matcher)}, or {@link #isA(Class)}.
+ * @param matcher the matcher to wrap
+ */
public Is(Matcher matcher) {
this.matcher = matcher;
}
diff --git a/hamcrest/src/main/java/org/hamcrest/core/IsAnything.java b/hamcrest/src/main/java/org/hamcrest/core/IsAnything.java
index 7e23e6893..9d1a51b86 100644
--- a/hamcrest/src/main/java/org/hamcrest/core/IsAnything.java
+++ b/hamcrest/src/main/java/org/hamcrest/core/IsAnything.java
@@ -6,19 +6,33 @@
/**
* A matcher that always returns true.
+ *
+ * @param the matched value type
*/
public class IsAnything extends BaseMatcher {
private final String message;
+ /**
+ * Constructor, best called from {@link #anything()}.
+ */
public IsAnything() {
this("ANYTHING");
}
+ /**
+ * Constructor, best called from {@link #anything(String)}.
+ * @param message matcher description
+ */
public IsAnything(String message) {
this.message = message;
}
+ /**
+ * Always returns true.
+ * @param o the object against which the matcher is evaluated.
+ * @return true
+ */
@Override
public boolean matches(Object o) {
return true;
diff --git a/hamcrest/src/main/java/org/hamcrest/core/IsCollectionContaining.java b/hamcrest/src/main/java/org/hamcrest/core/IsCollectionContaining.java
index fec503997..f3279bbd4 100644
--- a/hamcrest/src/main/java/org/hamcrest/core/IsCollectionContaining.java
+++ b/hamcrest/src/main/java/org/hamcrest/core/IsCollectionContaining.java
@@ -5,6 +5,7 @@
import org.hamcrest.TypeSafeDiagnosingMatcher;
/**
+ * @param the collection element type
* @deprecated As of release 2.1, replaced by {@link IsIterableContaining}.
*/
@Deprecated
@@ -12,6 +13,14 @@ public class IsCollectionContaining extends TypeSafeDiagnosingMatcher delegate;
+ /**
+ * Constructor, best called from one of the static factory methods.
+ * @param elementMatcher matches the expected element
+ * @see #hasItem(Object)
+ * @see #hasItem(Matcher)
+ * @see #hasItems(Object[])
+ * @see #hasItems(Matcher[])
+ */
public IsCollectionContaining(Matcher elementMatcher) {
this.delegate = new IsIterableContaining<>(elementMatcher);
}
diff --git a/hamcrest/src/main/java/org/hamcrest/core/IsEqual.java b/hamcrest/src/main/java/org/hamcrest/core/IsEqual.java
index ddb91c501..388ac52fc 100644
--- a/hamcrest/src/main/java/org/hamcrest/core/IsEqual.java
+++ b/hamcrest/src/main/java/org/hamcrest/core/IsEqual.java
@@ -8,12 +8,18 @@
/**
* Is the value equal to another value, as tested by the
- * {@link java.lang.Object#equals} invokedMethod?
+ * {@link java.lang.Object#equals} method.
+ *
+ * @param the matched value type
*/
public class IsEqual extends BaseMatcher {
private final Object expectedValue;
+ /**
+ * Constructor, best called from {@link #equalTo(Object)} or {@link #equalToObject(Object)}.
+ * @param equalArg the expected value
+ */
public IsEqual(T equalArg) {
expectedValue = equalArg;
}
diff --git a/hamcrest/src/main/java/org/hamcrest/core/IsIterableContaining.java b/hamcrest/src/main/java/org/hamcrest/core/IsIterableContaining.java
index 915e56c3a..070e3e95b 100644
--- a/hamcrest/src/main/java/org/hamcrest/core/IsIterableContaining.java
+++ b/hamcrest/src/main/java/org/hamcrest/core/IsIterableContaining.java
@@ -10,10 +10,22 @@
import static org.hamcrest.core.AllOf.allOf;
import static org.hamcrest.core.IsEqual.equalTo;
+/**
+ * Tests if an iterable contains matching elements.
+ * @param