add formal JavaDoc for factory methods in hamcrest-library beans and most of hamcrest-library collection. This goes partway to addressing issue 19 (on the google code issue tracker) - Add documentation to Matcher static factories

scarytom · scarytom · commit af548a4a2375 · 2012-05-20T15:22:25.000+01:00
diff --git a/hamcrest-library/src/main/java/org/hamcrest/beans/HasProperty.java b/hamcrest-library/src/main/java/org/hamcrest/beans/HasProperty.java
@@ -43,6 +43,16 @@ public void describeTo(Description description) {
         description.appendText("hasProperty(").appendValue(propertyName).appendText(")");
     }
 
+    /**
+     * Creates a matcher that matches when the examined object has a JavaBean property
+     * with the specified name.
+     * <p/>
+     * For example:
+     * <pre>assertThat(myBean, hasProperty("foo"))</pre>
+     * 
+     * @param propertyName
+     *     the name of the JavaBean property that examined beans should possess
+     */
     @Factory
     public static <T> Matcher<T> hasProperty(String propertyName) {
         return new HasProperty<T>(propertyName);
diff --git a/hamcrest-library/src/main/java/org/hamcrest/beans/HasPropertyWithValue.java b/hamcrest-library/src/main/java/org/hamcrest/beans/HasPropertyWithValue.java
@@ -2,11 +2,15 @@
  */
 package org.hamcrest.beans;
 
-import org.hamcrest.*;
-
 import java.beans.PropertyDescriptor;
 import java.lang.reflect.Method;
 
+import org.hamcrest.Condition;
+import org.hamcrest.Description;
+import org.hamcrest.Factory;
+import org.hamcrest.Matcher;
+import org.hamcrest.TypeSafeDiagnosingMatcher;
+
 import static org.hamcrest.Condition.matched;
 import static org.hamcrest.Condition.notMatched;
 import static org.hamcrest.beans.PropertyUtil.NO_ARGUMENTS;
@@ -20,35 +24,33 @@
  * <h2>Example Usage</h2>
  * 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: <code>
+ * methods for it's properties:
+ * <pre>
  * public class Person {
- * private String name;
- * <p/>
- * public Person(String person) {
- * this.person = person;
- * }
- * <p/>
- * public String getName() {
- * return name;
- * }
- * }
- * </code> 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: <code>
+ *   private String name;
+ *   public Person(String person) {
+ *     this.person = person;
+ *   }
+ *   public String getName() {
+ *     return name;
+ *   }
+ * }</pre>
+ * 
+ * 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:
+ * <pre>
  * public interface PersonGenerationListener {
- * public void personGenerated(Person person);
- * }
- * </code>
+ *   public void personGenerated(Person person);
+ * }</pre>
+ * 
  * In order to check that the code under test generates a person with name
  * "Iain" we would do the following:
- * <p/>
- * <code>
+ * <pre>
  * Mock personGenListenerMock = mock(PersonGenerationListener.class);
  * personGenListenerMock.expects(once()).method("personGenerated").with(and(isA(Person.class), hasProperty("Name", eq("Iain")));
- * PersonGenerationListener listener = (PersonGenerationListener)personGenListenerMock.proxy();
- * </code>
- * <p/>
+ * PersonGenerationListener listener = (PersonGenerationListener)personGenListenerMock.proxy();</pre>
+ * 
  * 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
  * when trying to invoke it then this is treated as an evaluation failure and
@@ -131,8 +133,20 @@ public Condition<Method> apply(PropertyDescriptor property, Description mismatch
         };
     }
 
+    /**
+     * Creates a matcher that matches when the examined object has a JavaBean property
+     * with the specified name whose value satisfies the specified matcher.
+     * <p/>
+     * For example:
+     * <pre>assertThat(myBean, hasProperty("foo", equalTo("bar"))</pre>
+     * 
+     * @param propertyName
+     *     the name of the JavaBean property that examined beans should possess
+     * @param valueMatcher
+     *     a matcher for the value of the specified property of the examined bean
+     */
     @Factory
-    public static <T> Matcher<T> hasProperty(String propertyName, Matcher<?> value) {
-        return new HasPropertyWithValue<T>(propertyName, value);
+    public static <T> Matcher<T> hasProperty(String propertyName, Matcher<?> valueMatcher) {
+        return new HasPropertyWithValue<T>(propertyName, valueMatcher);
     }
 }
diff --git a/hamcrest-library/src/main/java/org/hamcrest/beans/SamePropertyValuesAs.java b/hamcrest-library/src/main/java/org/hamcrest/beans/SamePropertyValuesAs.java
@@ -120,6 +120,17 @@ private static Object readProperty(Method method, Object target) {
         }
     }
 
+    /**
+     * 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.
+     * <p/>
+     * For example:
+     * <pre>assertThat(myBean, samePropertyValuesAs(myExpectedBean))</pre>
+     * 
+     * @param expectedBean
+     *     the bean against which examined beans are compared
+     */
     @Factory
     public static <T> Matcher<T> samePropertyValuesAs(T expectedBean) {
         return new SamePropertyValuesAs<T>(expectedBean);
diff --git a/hamcrest-library/src/main/java/org/hamcrest/collection/IsArray.java b/hamcrest-library/src/main/java/org/hamcrest/collection/IsArray.java
@@ -80,7 +80,15 @@ protected String descriptionEnd() {
     }
     
     /**
-     * Evaluates to true only if each matcher[i] is satisfied by array[i].
+     * Creates a matcher that matches arrays whose elements are satisfied by the specified matchers.  Matches
+     * positively only if the number of matchers specified is equal to the length of the examined array and
+     * each matcher[i] is satisfied by array[i].
+     * <p/>
+     * For example:
+     * <pre>assertThat(new Integer[]{1,2,3}, is(array(equalTo(1), equalTo(2), equalTo(3))))</pre>
+     * 
+     * @param elementMatchers
+     *     the matchers that the elements of examined arrays should satisfy
      */
     @Factory
     public static <T> IsArray<T> array(Matcher<? super T>... elementMatchers) {
diff --git a/hamcrest-library/src/main/java/org/hamcrest/collection/IsArrayContaining.java b/hamcrest-library/src/main/java/org/hamcrest/collection/IsArrayContaining.java
@@ -30,7 +30,7 @@ public boolean matchesSafely(T[] array) {
     
     @Override
     public void describeMismatchSafely(T[] item, Description mismatchDescription) {
-      super.describeMismatch(Arrays.asList(item), mismatchDescription);
+        super.describeMismatch(Arrays.asList(item), mismatchDescription);
     };
 
     @Override
@@ -41,18 +41,31 @@ public void describeTo(Description description) {
     }
 
     /**
-     * Evaluates to true if any item in an array satisfies the given matcher.
+     * Creates a matcher for arrays that matches when the examined array contains at least one item
+     * that is matched by the specified <code>elementMatcher</code>.  Whilst matching, the traversal
+     * of the examined array will stop as soon as a matching element is found.
+     * <p/>
+     * For example:
+     * <pre>assertThat(new String[] {"foo", "bar"}, hasItemInArray(startsWith("ba")))</pre>
+     * 
+     * @param elementMatcher
+     *     the matcher to apply to elements in examined arrays
      */
     @Factory
     public static <T> Matcher<T[]> hasItemInArray(Matcher<? super T> elementMatcher) {
         return new IsArrayContaining<T>(elementMatcher);
     }
 
     /**
-     * This is a shortcut to the frequently used hasItemInArray(equalTo(x)).
-     *
-     * For example,  assertThat(hasItemInArray(equal_to(x)))
-     *          vs.  assertThat(hasItemInArray(x))
+     * A shortcut to the frequently used <code>hasItemInArray(equalTo(x))</code>.
+     * <p/>
+     * For example:
+     * <pre>assertThat(hasItemInArray(x))</pre>
+     * instead of:
+     * <pre>assertThat(hasItemInArray(equalTo(x)))</pre>
+     * 
+     * @param element
+     *     the element that should be present in examined arrays
      */
     @Factory
     public static <T> Matcher<T[]> hasItemInArray(T element) {
diff --git a/hamcrest-library/src/main/java/org/hamcrest/collection/IsArrayWithSize.java b/hamcrest-library/src/main/java/org/hamcrest/collection/IsArrayWithSize.java
@@ -21,26 +21,42 @@ protected Integer featureValueOf(E[] actual) {
     }
 
     /**
-     * Does array size satisfy a given matcher?
+     * Creates a matcher for arrays that matches when the <code>length</code> of the array
+     * satisfies the specified matcher.
+     * <p/>
+     * For example:
+     * <pre>assertThat(new String[]{"foo", "bar"}, arrayWithSize(equalTo(2)))</pre>
+     * 
+     * @param sizeMatcher
+     *     a matcher for the length of an examined array
      */
     @Factory
     public static <E> Matcher<E[]> arrayWithSize(Matcher<? super Integer> sizeMatcher) {
         return new IsArrayWithSize<E>(sizeMatcher);
     }
 
     /**
-     * This is a shortcut to the frequently used arrayWithSize(equalTo(x)).
-     *
-     * For example,  assertThat(arrayWithSize(equal_to(x)))
-     *          vs.  assertThat(arrayWithSize(x))
+     * Creates a matcher for arrays that matches when the <code>length</code> of the array
+     * equals the specified <code>size</code>.
+     * <p/>
+     * For example:
+     * <pre>assertThat(new String[]{"foo", "bar"}, arrayWithSize(2))</pre>
+     * 
+     * @param size
+     *     the length that an examined array must have for a positive match
      */
     @Factory
     public static <E> Matcher<E[]> arrayWithSize(int size) {
         return arrayWithSize(equalTo(size));
     }
 
     /**
-     * Matches an empty array.
+     * Creates a matcher for arrays that matches when the <code>length</code> of the array
+     * is zero.
+     * <p/>
+     * For example:
+     * <pre>assertThat(new String[0], emptyArray())</pre>
+     * 
      */
     @Factory
     public static <E> Matcher<E[]> emptyArray() {
diff --git a/hamcrest-library/src/main/java/org/hamcrest/collection/IsCollectionWithSize.java b/hamcrest-library/src/main/java/org/hamcrest/collection/IsCollectionWithSize.java
@@ -22,19 +22,29 @@ protected Integer featureValueOf(Collection<? extends E> actual) {
     }
 
     /**
-     * Does collection size satisfy a given matcher?
+     * Creates a matcher for {@link Collection}s that matches when the <code>size()</code> method returns
+     * a value that satisfies the specified matcher.
+     * <p/>
+     * For example:
+     * <pre>assertThat(Arrays.asList("foo", "bar"), hasSize(equalTo(2)))</pre>
+     * 
+     * @param sizeMatcher
+     *     a matcher for the size of an examined {@link Collection}
      */
     @Factory
-    public static <E> Matcher<Collection<? extends E>> hasSize(Matcher<? super Integer> size) {
-        return new IsCollectionWithSize<E>(size);
+    public static <E> Matcher<Collection<? extends E>> hasSize(Matcher<? super Integer> sizeMatcher) {
+        return new IsCollectionWithSize<E>(sizeMatcher);
     }
 
-
     /**
-     * This is a shortcut to the frequently used hasSize(equalTo(x)).
-     *
-     * For example,  assertThat(hasSize(equal_to(x)))
-     *          vs.  assertThat(hasSize(x))
+     * Creates a matcher for {@link Collection}s that matches when the <code>size()</code> method returns
+     * a value equal to the specified <code>size</code>.
+     * <p/>
+     * For example:
+     * <pre>assertThat(Arrays.asList("foo", "bar"), hasSize(2))</pre>
+     * 
+     * @param size
+     *     the expected size of an examined {@link Collection}
      */
     @Factory
     public static <E> Matcher<Collection<? extends E>> hasSize(int size) {
diff --git a/hamcrest-library/src/main/java/org/hamcrest/collection/IsEmptyCollection.java b/hamcrest-library/src/main/java/org/hamcrest/collection/IsEmptyCollection.java
@@ -27,9 +27,14 @@ public void describeTo(Description description) {
         description.appendText("an empty collection");
     }
 
-    /**
-     * Matches an empty collection.
-     */
+  /**
+   * Creates a matcher for {@link Collection}s matching examined collections whose <code>isEmpty</code>
+   * method returns <code>true</code>.
+   * <p/>
+   * For example:
+   * <pre>assertThat(new ArrayList&lt;String&gt;(), is(empty()))</pre>
+   * 
+   */
     @Factory
     public static <E> Matcher<Collection<? extends E>> empty() {
         return new IsEmptyCollection<E>();
diff --git a/hamcrest-library/src/main/java/org/hamcrest/collection/IsEmptyIterable.java b/hamcrest-library/src/main/java/org/hamcrest/collection/IsEmptyIterable.java
@@ -25,7 +25,11 @@ public void describeTo(Description description) {
     }
 
     /**
-     * Matches an empty iterable.
+     * Creates a matcher for {@link Iterable}s matching examined iterables that yield no items.
+     * <p/>
+     * For example:
+     * <pre>assertThat(new ArrayList&lt;String&gt;(), is(emptyIterable()))</pre>
+     * 
      */
     @Factory
     public static <E> Matcher<Iterable<? extends E>> emptyIterable() {
diff --git a/hamcrest-library/src/main/java/org/hamcrest/collection/IsIn.java b/hamcrest-library/src/main/java/org/hamcrest/collection/IsIn.java
@@ -30,16 +30,40 @@ public void describeTo(Description buffer) {
         buffer.appendValueList("{", ", ", "}", collection);
     }
     
+    /**
+     * Creates a matcher that matches when the examined object is found within the
+     * specified collection.
+     * 
+     * @param collection
+     *     the collection in which matching items must be found
+     * 
+     */
     @Factory
     public static <T> Matcher<T> isIn(Collection<T> collection) {
         return new IsIn<T>(collection);
     }
-    
+
+    /**
+     * Creates a matcher that matches when the examined object is found within the
+     * specified array.
+     * 
+     * @param elements
+     *     the array in which matching items must be found
+     * 
+     */
     @Factory
     public static <T> Matcher<T> isIn(T[] elements) {
         return new IsIn<T>(elements);
     }
     
+    /**
+     * Creates a matcher that matches when the examined object is equal to one of the
+     * specified elements.
+     * 
+     * @param elements
+     *     the elements amongst which matching items will be found 
+     * 
+     */
     @Factory
     public static <T> Matcher<T> isOneOf(T... elements) {
         return isIn(elements);
diff --git a/hamcrest-library/src/main/java/org/hamcrest/collection/IsIterableContainingInAnyOrder.java b/hamcrest-library/src/main/java/org/hamcrest/collection/IsIterableContainingInAnyOrder.java
diff --git a/hamcrest-library/src/main/java/org/hamcrest/collection/IsIterableContainingInOrder.java b/hamcrest-library/src/main/java/org/hamcrest/collection/IsIterableContainingInOrder.java
diff --git a/hamcrest-library/src/main/java/org/hamcrest/collection/IsIterableWithSize.java b/hamcrest-library/src/main/java/org/hamcrest/collection/IsIterableWithSize.java
diff --git a/hamcrest-library/src/main/java/org/hamcrest/collection/IsMapContaining.java b/hamcrest-library/src/main/java/org/hamcrest/collection/IsMapContaining.java
