Skip to content

Commit 26eadba

Browse files
scarytomscarytom
committed
add formal JavaDoc for remaining factory methods in hamcrest-library. This should address issue 19 (on the google code issue tracker) - Add documentation to Matcher static factories
1 parent af548a4 commit 26eadba

14 files changed

+311
-36
lines changed

‎hamcrest-library/src/main/java/org/hamcrest/collection/IsArrayContainingInAnyOrder.java

Lines changed: 52 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -37,17 +37,64 @@ public void describeTo(Description description) {
3737
.appendText(" in any order");
3838
}
3939

40+
/**
41+
* Creates an order agnostic matcher for arrays that matches when each item in the
42+
* examined array satisfies one matcher anywhere in the specified matchers.
43+
* For a positive match, the examined array must be of the same length as the number of
44+
* specified matchers.
45+
* <p/>
46+
* N.B. each of the specified matchers will only be used once during a given examination, so be
47+
* careful when specifying matchers that may be satisfied by more than one entry in an examined
48+
* array.
49+
* <p>
50+
* For example:
51+
* <pre>assertThat(new String[]{"foo", "bar"}, arrayContainingInAnyOrder(equalTo("bar"), equalTo("foo")))</pre>
52+
*
53+
* @param itemMatchers
54+
* a list of matchers, each of which must be satisfied by an entry in an examined array
55+
*/
4056
@Factory
41-
public static <E> Matcher<E[]> arrayContainingInAnyOrder(Matcher<? super E>... matchers) {
42-
return arrayContainingInAnyOrder(Arrays.asList(matchers));
57+
public static <E> Matcher<E[]> arrayContainingInAnyOrder(Matcher<? super E>... itemMatchers) {
58+
return arrayContainingInAnyOrder(Arrays.asList(itemMatchers));
4359
}
4460

45-
61+
/**
62+
* Creates an order agnostic matcher for arrays that matches when each item in the
63+
* examined array satisfies one matcher anywhere in the specified collection of matchers.
64+
* For a positive match, the examined array must be of the same length as the specified collection
65+
* of matchers.
66+
* <p/>
67+
* N.B. each matcher in the specified collection will only be used once during a given
68+
* examination, so be careful when specifying matchers that may be satisfied by more than
69+
* one entry in an examined array.
70+
* <p>
71+
* For example:
72+
* <pre>assertThat(new String[]{"foo", "bar"}, arrayContainingInAnyOrder(Arrays.asList(equalTo("bar"), equalTo("foo"))))</pre>
73+
*
74+
* @param itemMatchers
75+
* a list of matchers, each of which must be satisfied by an item provided by an examined array
76+
*/
4677
@Factory
47-
public static <E> Matcher<E[]> arrayContainingInAnyOrder(Collection<Matcher<? super E>> matchers) {
48-
return new IsArrayContainingInAnyOrder<E>(matchers);
78+
public static <E> Matcher<E[]> arrayContainingInAnyOrder(Collection<Matcher<? super E>> itemMatchers) {
79+
return new IsArrayContainingInAnyOrder<E>(itemMatchers);
4980
}
5081

82+
/**
83+
* Creates an order agnostic matcher for arrays that matches when each item in the
84+
* examined array is logically equal to one item anywhere in the specified items.
85+
* For a positive match, the examined array must be of the same length as the number of
86+
* specified items.
87+
* <p/>
88+
* N.B. each of the specified items will only be used once during a given examination, so be
89+
* careful when specifying items that may be equal to more than one entry in an examined
90+
* array.
91+
* <p>
92+
* For example:
93+
* <pre>assertThat(new String[]{"foo", "bar"}, containsInAnyOrder("bar", "foo"))</pre>
94+
*
95+
* @param items
96+
* the items that must equal the entries of an examined array, in any order
97+
*/
5198
@Factory
5299
public static <E> Matcher<E[]> arrayContainingInAnyOrder(E... items) {
53100
List<Matcher<? super E>> matchers = new ArrayList<Matcher<? super E>>();

‎hamcrest-library/src/main/java/org/hamcrest/collection/IsArrayContainingInOrder.java

Lines changed: 37 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -36,6 +36,17 @@ public void describeTo(Description description) {
3636
description.appendList("[", ", ", "]", matchers);
3737
}
3838

39+
/**
40+
* Creates a matcher for arrays that matcheswhen each item in the examined array is
41+
* logically equal to the corresponding item in the specified items. For a positive match,
42+
* the examined array must be of the same length as the number of specified items.
43+
* <p/>
44+
* For example:
45+
* <pre>assertThat(new String[]{"foo", "bar"}, contains("foo", "bar"))</pre>
46+
*
47+
* @param items
48+
* the items that must equal the items within an examined array
49+
*/
3950
@Factory
4051
public static <E> Matcher<E[]> arrayContaining(E... items) {
4152
List<Matcher<? super E>> matchers = new ArrayList<Matcher<? super E>>();
@@ -45,13 +56,35 @@ public static <E> Matcher<E[]> arrayContaining(E... items) {
4556
return arrayContaining(matchers);
4657
}
4758

59+
/**
60+
* Creates a matcher for arrays that matches when each item in the examined array satisfies the
61+
* corresponding matcher in the specified matchers. For a positive match, the examined array
62+
* must be of the same length as the number of specified matchers.
63+
* <p/>
64+
* For example:
65+
* <pre>assertThat(new String[]{"foo", "bar"}, contains(equalTo("foo"), equalTo("bar")))</pre>
66+
*
67+
* @param itemMatchers
68+
* the matchers that must be satisfied by the items in the examined array
69+
*/
4870
@Factory
49-
public static <E> Matcher<E[]> arrayContaining(Matcher<? super E>... matchers) {
50-
return arrayContaining(asList(matchers));
71+
public static <E> Matcher<E[]> arrayContaining(Matcher<? super E>... itemMatchers) {
72+
return arrayContaining(asList(itemMatchers));
5173
}
5274

75+
/**
76+
* Creates a matcher for arrays that matches when each item in the examined array satisfies the
77+
* corresponding matcher in the specified list of matchers. For a positive match, the examined array
78+
* must be of the same length as the specified list of matchers.
79+
* <p/>
80+
* For example:
81+
* <pre>assertThat(new String[]{"foo", "bar"}, contains(Arrays.asList(equalTo("foo"), equalTo("bar"))))</pre>
82+
*
83+
* @param itemMatchers
84+
* a list of matchers, each of which must be satisfied by the corresponding item in an examined array
85+
*/
5386
@Factory
54-
public static <E> Matcher<E[]> arrayContaining(List<Matcher<? super E>> matchers) {
55-
return new IsArrayContainingInOrder<E>(matchers);
87+
public static <E> Matcher<E[]> arrayContaining(List<Matcher<? super E>> itemMatchers) {
88+
return new IsArrayContainingInOrder<E>(itemMatchers);
5689
}
5790
}

‎hamcrest-library/src/main/java/org/hamcrest/collection/IsIn.java

Lines changed: 10 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -33,6 +33,9 @@ public void describeTo(Description buffer) {
3333
/**
3434
* Creates a matcher that matches when the examined object is found within the
3535
* specified collection.
36+
* <p/>
37+
* For example:
38+
* <pre>assertThat("foo", isIn(Arrays.asList("bar", "foo")))</pre>
3639
*
3740
* @param collection
3841
* the collection in which matching items must be found
@@ -46,6 +49,9 @@ public static <T> Matcher<T> isIn(Collection<T> collection) {
4649
/**
4750
* Creates a matcher that matches when the examined object is found within the
4851
* specified array.
52+
* <p/>
53+
* For example:
54+
* <pre>assertThat("foo", isIn(new String[]{"bar", "foo"}))</pre>
4955
*
5056
* @param elements
5157
* the array in which matching items must be found
@@ -59,7 +65,10 @@ public static <T> Matcher<T> isIn(T[] elements) {
5965
/**
6066
* Creates a matcher that matches when the examined object is equal to one of the
6167
* specified elements.
62-
*
68+
* <p/>
69+
* For example:
70+
* <pre>assertThat("foo", isIn("bar", "foo"))</pre>
71+
*
6372
* @param elements
6473
* the elements amongst which matching items will be found
6574
*

‎hamcrest-library/src/main/java/org/hamcrest/collection/IsIterableContainingInAnyOrder.java

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -113,7 +113,7 @@ public static <E> Matcher<Iterable<? extends E>> containsInAnyOrder(final Matche
113113
* N.B. each of the specified matchers will only be used once during a given examination, so be
114114
* careful when specifying matchers that may be satisfied by more than one entry in an examined
115115
* iterable.
116-
* <p>
116+
* <p/>
117117
* For example:
118118
* <pre>assertThat(Arrays.asList("foo", "bar"), containsInAnyOrder(equalTo("bar"), equalTo("foo")))</pre>
119119
*
@@ -134,7 +134,7 @@ public static <T> Matcher<Iterable<? extends T>> containsInAnyOrder(Matcher<? su
134134
* N.B. each of the specified items will only be used once during a given examination, so be
135135
* careful when specifying items that may be equal to more than one entry in an examined
136136
* iterable.
137-
* <p>
137+
* <p/>
138138
* For example:
139139
* <pre>assertThat(Arrays.asList("foo", "bar"), containsInAnyOrder("bar", "foo"))</pre>
140140
*
@@ -155,12 +155,12 @@ public static <T> Matcher<Iterable<? extends T>> containsInAnyOrder(T... items)
155155
* Creates an order agnostic matcher for {@link Iterable}s that matches when a single pass over
156156
* the examined {@link Iterable} yields a series of items, each satisfying one matcher anywhere
157157
* in the specified collection of matchers. For a positive match, the examined iterable
158-
* must be of the same length as the specified list of matchers.
158+
* must be of the same length as the specified collection of matchers.
159159
* <p/>
160160
* N.B. each matcher in the specified collection will only be used once during a given
161161
* examination, so be careful when specifying matchers that may be satisfied by more than
162162
* one entry in an examined iterable.
163-
* <p>
163+
* <p/>
164164
* For example:
165165
* <pre>assertThat(Arrays.asList("foo", "bar"), containsInAnyOrder(Arrays.asList(equalTo("bar"), equalTo("foo"))))</pre>
166166
*

‎hamcrest-library/src/main/java/org/hamcrest/number/IsCloseTo.java

Lines changed: 12 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -45,10 +45,20 @@ private double actualDelta(Double item) {
4545
return (Math.abs((item - value)) - delta);
4646
}
4747

48-
48+
/**
49+
* Creates a matcher of {@link Double}s that matches when an examined double is equal
50+
* to the specified <code>operand</code>, within a range of +/- <code>error</code>.
51+
* <p/>
52+
* For example:
53+
* <pre>assertThat(1.03, is(closeTo(1.0, 0.03)))</pre>
54+
*
55+
* @param operand
56+
* the expected value of matching doubles
57+
* @param error
58+
* the delta (+/-) within which matches will be allowed
59+
*/
4960
@Factory
5061
public static Matcher<Double> closeTo(double operand, double error) {
5162
return new IsCloseTo(operand, error);
5263
}
53-
5464
}

‎hamcrest-library/src/main/java/org/hamcrest/number/OrderingComparison.java

Lines changed: 54 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -55,39 +55,88 @@ private static String asText(int comparison) {
5555
}
5656

5757
/**
58-
* @return Is value = expected?
58+
* Creates a matcher of {@link Comparable} object that matches when the examined object is
59+
* equal to the specified value, as reported by the <code>compareTo</code> method of the
60+
* <b>examined</b> object.
61+
* <p/>
62+
* For example:
63+
* <pre>assertThat(1, comparesEqualTo(1))</pre>
64+
*
65+
* @param value
66+
* the value which, when passed to the compareTo method of the examined object, should return zero
67+
*
5968
*/
6069
@Factory
6170
public static <T extends Comparable<T>> Matcher<T> comparesEqualTo(T value) {
6271
return new OrderingComparison<T>(value, EQUAL, EQUAL);
6372
}
6473

6574
/**
66-
* Is value > expected?
75+
* Creates a matcher of {@link Comparable} object that matches when the examined object is
76+
* greater than the specified value, as reported by the <code>compareTo</code> method of the
77+
* <b>examined</b> object.
78+
* <p/>
79+
* For example:
80+
* <pre>assertThat(2, greaterThan(1))</pre>
81+
*
82+
* @param value
83+
* the value which, when passed to the compareTo method of the examined object, should return greater
84+
* than zero
85+
*
6786
*/
6887
@Factory
6988
public static <T extends Comparable<T>> Matcher<T> greaterThan(T value) {
7089
return new OrderingComparison<T>(value, GREATER_THAN, GREATER_THAN);
7190
}
7291

7392
/**
74-
* Is value >= expected?
93+
* Creates a matcher of {@link Comparable} object that matches when the examined object is
94+
* greater than or equal to the specified value, as reported by the <code>compareTo</code> method
95+
* of the <b>examined</b> object.
96+
* <p/>
97+
* For example:
98+
* <pre>assertThat(1, greaterThanOrEqualTo(1))</pre>
99+
*
100+
* @param value
101+
* the value which, when passed to the compareTo method of the examined object, should return greater
102+
* than or equal to zero
103+
*
75104
*/
76105
@Factory
77106
public static <T extends Comparable<T>> Matcher<T> greaterThanOrEqualTo(T value) {
78107
return new OrderingComparison<T>(value, EQUAL, GREATER_THAN);
79108
}
80109

81110
/**
82-
* Is value < expected?
111+
* Creates a matcher of {@link Comparable} object that matches when the examined object is
112+
* less than the specified value, as reported by the <code>compareTo</code> method of the
113+
* <b>examined</b> object.
114+
* <p/>
115+
* For example:
116+
* <pre>assertThat(1, lessThan(2))</pre>
117+
*
118+
* @param value
119+
* the value which, when passed to the compareTo method of the examined object, should return less
120+
* than zero
121+
*
83122
*/
84123
@Factory
85124
public static <T extends Comparable<T>> Matcher<T> lessThan(T value) {
86125
return new OrderingComparison<T>(value, LESS_THAN, LESS_THAN);
87126
}
88127

89128
/**
90-
* Is value <= expected?
129+
* Creates a matcher of {@link Comparable} object that matches when the examined object is
130+
* less than or equal to the specified value, as reported by the <code>compareTo</code> method
131+
* of the <b>examined</b> object.
132+
* <p/>
133+
* For example:
134+
* <pre>assertThat(1, lessThanOrEqualTo(1))</pre>
135+
*
136+
* @param value
137+
* the value which, when passed to the compareTo method of the examined object, should return less
138+
* than or equal to zero
139+
*
91140
*/
92141
@Factory
93142
public static <T extends Comparable<T>> Matcher<T> lessThanOrEqualTo(T value) {

‎hamcrest-library/src/main/java/org/hamcrest/object/HasToString.java

Lines changed: 16 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -17,18 +17,29 @@ protected String featureValueOf(T actual) {
1717
}
1818

1919
/**
20-
* Evaluates whether item.toString() satisfies a given matcher.
20+
* Creates a matcher that matches any examined object whose <code>toString</code> method
21+
* returns a value that satisfies the specified matcher.
22+
* <p/>
23+
* For example:
24+
* <pre>assertThat(true, hasToString(equalTo("TRUE")))</pre>
25+
*
26+
* @param toStringMatcher
27+
* the matcher used to verify the toString result
2128
*/
2229
@Factory
2330
public static <T> Matcher<T> hasToString(Matcher<? super String> toStringMatcher) {
2431
return new HasToString<T>(toStringMatcher);
2532
}
2633

2734
/**
28-
* This is a shortcut to the frequently used has_string(equalTo(x)).
29-
*
30-
* For example, assertThat(hasToString(equal_to(x)))
31-
* vs. assertThat(hasToString(x))
35+
* Creates a matcher that matches any examined object whose <code>toString</code> method
36+
* returns a value equalTo the specified string.
37+
* <p/>
38+
* For example:
39+
* <pre>assertThat(true, hasToString("TRUE"))</pre>
40+
*
41+
* @param expectedToString
42+
* the expected toString result
3243
*/
3344
@Factory
3445
public static <T> Matcher<T> hasToString(String expectedToString) {

‎hamcrest-library/src/main/java/org/hamcrest/object/IsCompatibleType.java

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -27,6 +27,16 @@ public void describeTo(Description description) {
2727
description.appendText("type < ").appendText(type.getName());
2828
}
2929

30+
/**
31+
* Creates a matcher of {@link Class} that matches when the specified baseType is
32+
* assignable from the examined class.
33+
* <p/>
34+
* For example:
35+
* <pre>assertThat(Integer.class, typeCompatibleWith(Number.class))</pre>
36+
*
37+
* @param baseType
38+
* the base class to examine classes against
39+
*/
3040
@Factory
3141
public static <T> Matcher<Class<?>> typeCompatibleWith(Class<T> baseType) {
3242
return new IsCompatibleType<T>(baseType);

‎hamcrest-library/src/main/java/org/hamcrest/object/IsEventFrom.java

Lines changed: 17 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -50,18 +50,31 @@ public void describeTo(Description description) {
5050
}
5151

5252
/**
53-
* Constructs an IsEventFrom Matcher that returns true for any object
53+
* Creates a matcher of {@link EventObject} that matches any object
5454
* derived from <var>eventClass</var> announced by <var>source</var>.
55+
* </p>
56+
* For example:
57+
* <pre>assertThat(myEvent, is(eventFrom(PropertyChangeEvent.class, myBean)))</pre>
58+
*
59+
* @param eventClass
60+
* the class of the event to match on
61+
* @param source
62+
* the source of the event
5563
*/
5664
@Factory
5765
public static Matcher<EventObject> eventFrom(Class<? extends EventObject> eventClass, Object source) {
5866
return new IsEventFrom(eventClass, source);
5967
}
6068

6169
/**
62-
* Constructs an IsEventFrom Matcher that returns true for any object
63-
* derived from {@link java.util.EventObject} announced by <var>source
64-
* </var>.
70+
* Creates a matcher of {@link EventObject} that matches any EventObject
71+
* announced by <var>source</var>.
72+
* </p>
73+
* For example:
74+
* <pre>assertThat(myEvent, is(eventFrom(myBean)))</pre>
75+
*
76+
* @param source
77+
* the source of the event
6578
*/
6679
@Factory
6780
public static Matcher<EventObject> eventFrom(Object source) {

0 commit comments

Comments
 (0)