Skip to content

Commit cfc64b8

Browse files
scarytomscarytom
committed
Add formal JavaDoc to all of the factory methods of the core matchers. This goes partway to addressing issue 19 (on the google code issue tracker) - Add documentation to Matcher static factories
1 parent ee3cb31 commit cfc64b8

16 files changed

+330
-104
lines changed

‎hamcrest-core/src/main/java/org/hamcrest/core/AllOf.java

Lines changed: 28 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -39,23 +39,32 @@ public void describeTo(Description description) {
3939
}
4040

4141
/**
42-
* Evaluates to true only if ALL of the passed in matchers evaluate to true.
42+
* Creates a matcher that matches if the examined object matches <b>ALL</b> of the specified matchers.
43+
* <p/>
44+
* For example:
45+
* <pre>assertThat("myValue", allOf(startsWith("my"), containsString("Val")))</pre>
4346
*/
4447
@Factory
4548
public static <T> Matcher<T> allOf(Iterable<Matcher<? super T>> matchers) {
4649
return new AllOf<T>(matchers);
4750
}
4851

4952
/**
50-
* Evaluates to true only if ALL of the passed in matchers evaluate to true.
53+
* Creates a matcher that matches if the examined object matches <b>ALL</b> of the specified matchers.
54+
* <p/>
55+
* For example:
56+
* <pre>assertThat("myValue", allOf(startsWith("my"), containsString("Val")))</pre>
5157
*/
5258
@Factory
5359
public static <T> Matcher<T> allOf(Matcher<? super T>... matchers) {
5460
return allOf(Arrays.asList(matchers));
5561
}
5662

5763
/**
58-
* Evaluates to true only if ALL of the passed in matchers evaluate to true.
64+
* Creates a matcher that matches if the examined object matches <b>ALL</b> of the specified matchers.
65+
* <p/>
66+
* For example:
67+
* <pre>assertThat("myValue", allOf(startsWith("my"), containsString("Val")))</pre>
5968
*/
6069
@Factory
6170
public static <T> Matcher<T> allOf(Matcher<? super T> first, Matcher<? super T> second) {
@@ -66,7 +75,10 @@ public static <T> Matcher<T> allOf(Matcher<? super T> first, Matcher<? super T>
6675
}
6776

6877
/**
69-
* Evaluates to true only if ALL of the passed in matchers evaluate to true.
78+
* Creates a matcher that matches if the examined object matches <b>ALL</b> of the specified matchers.
79+
* <p/>
80+
* For example:
81+
* <pre>assertThat("myValue", allOf(startsWith("my"), containsString("Val")))</pre>
7082
*/
7183
@Factory
7284
public static <T> Matcher<T> allOf(Matcher<? super T> first, Matcher<? super T> second, Matcher<? super T> third) {
@@ -78,7 +90,10 @@ public static <T> Matcher<T> allOf(Matcher<? super T> first, Matcher<? super T>
7890
}
7991

8092
/**
81-
* Evaluates to true only if ALL of the passed in matchers evaluate to true.
93+
* Creates a matcher that matches if the examined object matches <b>ALL</b> of the specified matchers.
94+
* <p/>
95+
* For example:
96+
* <pre>assertThat("myValue", allOf(startsWith("my"), containsString("Val")))</pre>
8297
*/
8398
@Factory
8499
public static <T> Matcher<T> allOf(Matcher<? super T> first, Matcher<? super T> second, Matcher<? super T> third, Matcher<? super T> fourth) {
@@ -91,7 +106,10 @@ public static <T> Matcher<T> allOf(Matcher<? super T> first, Matcher<? super T>
91106
}
92107

93108
/**
94-
* Evaluates to true only if ALL of the passed in matchers evaluate to true.
109+
* Creates a matcher that matches if the examined object matches <b>ALL</b> of the specified matchers.
110+
* <p/>
111+
* For example:
112+
* <pre>assertThat("myValue", allOf(startsWith("my"), containsString("Val")))</pre>
95113
*/
96114
@Factory
97115
public static <T> Matcher<T> allOf(Matcher<? super T> first, Matcher<? super T> second, Matcher<? super T> third, Matcher<? super T> fourth, Matcher<? super T> fifth) {
@@ -105,7 +123,10 @@ public static <T> Matcher<T> allOf(Matcher<? super T> first, Matcher<? super T>
105123
}
106124

107125
/**
108-
* Evaluates to true only if ALL of the passed in matchers evaluate to true.
126+
* Creates a matcher that matches if the examined object matches <b>ALL</b> of the specified matchers.
127+
* <p/>
128+
* For example:
129+
* <pre>assertThat("myValue", allOf(startsWith("my"), containsString("Val")))</pre>
109130
*/
110131
@Factory
111132
public static <T> Matcher<T> allOf(Matcher<? super T> first, Matcher<? super T> second, Matcher<? super T> third, Matcher<? super T> fourth, Matcher<? super T> fifth, Matcher<? super T> sixth) {

‎hamcrest-core/src/main/java/org/hamcrest/core/AnyOf.java

Lines changed: 28 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -29,23 +29,32 @@ public void describeTo(Description description) {
2929
}
3030

3131
/**
32-
* Evaluates to true if ANY of the passed in matchers evaluate to true.
32+
* Creates a matcher that matches if the examined object matches <b>ANY</b> of the specified matchers.
33+
* <p/>
34+
* For example:
35+
* <pre>assertThat("myValue", anyOf(startsWith("foo"), containsString("Val")))</pre>
3336
*/
3437
@Factory
3538
public static <T> AnyOf<T> anyOf(Iterable<Matcher<? super T>> matchers) {
3639
return new AnyOf<T>(matchers);
3740
}
3841

3942
/**
40-
* Evaluates to true if ANY of the passed in matchers evaluate to true.
43+
* Creates a matcher that matches if the examined object matches <b>ANY</b> of the specified matchers.
44+
* <p/>
45+
* For example:
46+
* <pre>assertThat("myValue", anyOf(startsWith("foo"), containsString("Val")))</pre>
4147
*/
4248
@Factory
4349
public static <T> AnyOf<T> anyOf(Matcher<? super T>... matchers) {
4450
return anyOf(Arrays.asList(matchers));
4551
}
4652

4753
/**
48-
* Evaluates to true if ANY of the passed in matchers evaluate to true.
54+
* Creates a matcher that matches if the examined object matches <b>ANY</b> of the specified matchers.
55+
* <p/>
56+
* For example:
57+
* <pre>assertThat("myValue", anyOf(startsWith("foo"), containsString("Val")))</pre>
4958
*/
5059
@Factory
5160
public static <T> AnyOf<T> anyOf(Matcher<T> first, Matcher<? super T> second) {
@@ -56,7 +65,10 @@ public static <T> AnyOf<T> anyOf(Matcher<T> first, Matcher<? super T> second) {
5665
}
5766

5867
/**
59-
* Evaluates to true if ANY of the passed in matchers evaluate to true.
68+
* Creates a matcher that matches if the examined object matches <b>ANY</b> of the specified matchers.
69+
* <p/>
70+
* For example:
71+
* <pre>assertThat("myValue", anyOf(startsWith("foo"), containsString("Val")))</pre>
6072
*/
6173
@Factory
6274
public static <T> AnyOf<T> anyOf(Matcher<T> first, Matcher<? super T> second, Matcher<? super T> third) {
@@ -68,7 +80,10 @@ public static <T> AnyOf<T> anyOf(Matcher<T> first, Matcher<? super T> second, Ma
6880
}
6981

7082
/**
71-
* Evaluates to true if ANY of the passed in matchers evaluate to true.
83+
* Creates a matcher that matches if the examined object matches <b>ANY</b> of the specified matchers.
84+
* <p/>
85+
* For example:
86+
* <pre>assertThat("myValue", anyOf(startsWith("foo"), containsString("Val")))</pre>
7287
*/
7388
@Factory
7489
public static <T> AnyOf<T> anyOf(Matcher<T> first, Matcher<? super T> second, Matcher<? super T> third, Matcher<? super T> fourth) {
@@ -81,7 +96,10 @@ public static <T> AnyOf<T> anyOf(Matcher<T> first, Matcher<? super T> second, Ma
8196
}
8297

8398
/**
84-
* Evaluates to true if ANY of the passed in matchers evaluate to true.
99+
* Creates a matcher that matches if the examined object matches <b>ANY</b> of the specified matchers.
100+
* <p/>
101+
* For example:
102+
* <pre>assertThat("myValue", anyOf(startsWith("foo"), containsString("Val")))</pre>
85103
*/
86104
@Factory
87105
public static <T> AnyOf<T> anyOf(Matcher<T> first, Matcher<? super T> second, Matcher<? super T> third, Matcher<? super T> fourth, Matcher<? super T> fifth) {
@@ -95,7 +113,10 @@ public static <T> AnyOf<T> anyOf(Matcher<T> first, Matcher<? super T> second, Ma
95113
}
96114

97115
/**
98-
* Evaluates to true if ANY of the passed in matchers evaluate to true.
116+
* Creates a matcher that matches if the examined object matches <b>ANY</b> of the specified matchers.
117+
* <p/>
118+
* For example:
119+
* <pre>assertThat("myValue", anyOf(startsWith("foo"), containsString("Val")))</pre>
99120
*/
100121
@Factory
101122
public static <T> AnyOf<T> anyOf(Matcher<T> first, Matcher<? super T> second, Matcher<? super T> third, Matcher<? super T> fourth, Matcher<? super T> fifth, Matcher<? super T> sixth) {

‎hamcrest-core/src/main/java/org/hamcrest/core/CombinableMatcher.java

Lines changed: 8 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -41,10 +41,10 @@ private ArrayList<Matcher<? super T>> templatedListWith(Matcher<? super T> other
4141
}
4242

4343
/**
44-
* This is useful for fluently combining matchers that must both pass. For example:
45-
* <pre>
46-
* assertThat(string, both(containsString("a")).and(containsString("b")));
47-
* </pre>
44+
* Creates a matcher that matches when both of the specified matchers match the examined object.
45+
* <p/>
46+
* For example:
47+
* <pre>assertThat("fab", both(containsString("a")).and(containsString("b")))</pre>
4848
*/
4949
@Factory
5050
public static <LHS> CombinableBothMatcher<LHS> both(Matcher<? super LHS> matcher) {
@@ -62,10 +62,10 @@ public CombinableMatcher<X> and(Matcher<? super X> other) {
6262
}
6363

6464
/**
65-
* This is useful for fluently combining matchers where either may pass, for example:
66-
* <pre>
67-
* assertThat(string, both(containsString("a")).and(containsString("b")));
68-
* </pre>
65+
* Creates a matcher that matches when either of the specified matchers match the examined object.
66+
* <p/>
67+
* For example:
68+
* <pre>assertThat("fan", either(containsString("a")).and(containsString("b")))</pre>
6969
*/
7070
@Factory
7171
public static <LHS> CombinableEitherMatcher<LHS> either(Matcher<? super LHS> matcher) {

‎hamcrest-core/src/main/java/org/hamcrest/core/DescribedAs.java

Lines changed: 12 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -54,7 +54,18 @@ public void describeMismatch(Object item, Description description) {
5454
}
5555

5656
/**
57-
* Wraps an existing matcher and overrides the description when it fails.
57+
* Wraps an existing matcher, overriding its description with that specified. All other functions are
58+
* delegated to the decorated matcher, including its mismatch description.
59+
* <p/>
60+
* For example:
61+
* <pre>describedAs("a big decimal equal to %0", equalTo(myBigDecimal), myBigDecimal.toPlainString())</pre>
62+
*
63+
* @param description
64+
* the new description for the wrapped matcher
65+
* @param
66+
* the matcher to wrap
67+
* @param
68+
* optional values to insert into the tokenised description
5869
*/
5970
@Factory
6071
public static <T> Matcher<T> describedAs(String description, Matcher<T> matcher, Object... values) {

‎hamcrest-core/src/main/java/org/hamcrest/core/Every.java

Lines changed: 9 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -30,8 +30,15 @@ public void describeTo(Description description) {
3030
}
3131

3232
/**
33-
* @param itemMatcher A matcher to apply to every element in a collection.
34-
* @return Evaluates to TRUE for a collection in which every item matches itemMatcher
33+
* Creates a matcher for {@link Iterable}s that only matches when a single pass over the
34+
* examined {@link Iterable} yields items that are all matched by the specified
35+
* <code>itemMatcher</code>.
36+
* <p/>
37+
* For example:
38+
* <pre>assertThat(Arrays.asList("bar", "baz"), everyItem(startsWith("ba")))</pre>
39+
*
40+
* @param itemMatcher
41+
* the matcher to apply to every item provided by the examined {@link Iterable}
3542
*/
3643
@Factory
3744
public static <U> Matcher<Iterable<U>> everyItem(final Matcher<U> itemMatcher) {

‎hamcrest-core/src/main/java/org/hamcrest/core/Is.java

Lines changed: 26 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -40,31 +40,39 @@ public void describeMismatch(Object item, Description mismatchDescription) {
4040
/**
4141
* Decorates another Matcher, retaining its behaviour, but allowing tests
4242
* to be slightly more expressive.
43-
*
44-
* For example: assertThat(cheese, equalTo(smelly))
45-
* vs. assertThat(cheese, is(equalTo(smelly)))
43+
* <p/>
44+
* For example:
45+
* <pre>assertThat(cheese, is(equalTo(smelly)))</pre>
46+
* instead of:
47+
* <pre>assertThat(cheese, equalTo(smelly))</pre>
48+
*
4649
*/
4750
@Factory
4851
public static <T> Matcher<T> is(Matcher<T> matcher) {
4952
return new Is<T>(matcher);
5053
}
5154

5255
/**
53-
* A shortcut to the frequently used is(equalTo(x)).
54-
*
55-
* For example: assertThat(cheese, is(equalTo(smelly)))
56-
* vs. assertThat(cheese, is(smelly))
56+
* A shortcut to the frequently used <code>is(equalTo(x))</code>.
57+
* <p/>
58+
* For example:
59+
* <pre>assertThat(cheese, is(smelly))</pre>
60+
* instead of:
61+
* <pre>assertThat(cheese, is(equalTo(smelly)))</pre>
62+
*
5763
*/
5864
@Factory
5965
public static <T> Matcher<T> is(T value) {
6066
return is(equalTo(value));
6167
}
6268

6369
/**
64-
* A shortcut to the frequently used is(instanceOf(SomeClass.class)).
65-
*
66-
* For example: assertThat(cheese, is(instanceOf(Cheddar.class)))
67-
* vs. assertThat(cheese, is(Cheddar.class))
70+
* A shortcut to the frequently used <code>is(instanceOf(SomeClass.class))</code>.
71+
* <p/>
72+
* For example:
73+
* <pre>assertThat(cheese, is(Cheddar.class))</pre>
74+
* instead of:
75+
* <pre>assertThat(cheese, is(instanceOf(Cheddar.class)))</pre>
6876
*
6977
* @deprecated use isA(Class<T> type) instead.
7078
*/
@@ -76,10 +84,13 @@ public static <T> Matcher<T> is(Class<T> type) {
7684
}
7785

7886
/**
79-
* A shortcut for the frequently used is(instanceOf(SomeClass.class)).
80-
*
81-
* For example: assertThat(cheese, is(instanceOf(Cheddar.class)))
82-
* vs. assertThat(cheese, isA(Cheddar.class))
87+
* A shortcut to the frequently used <code>is(instanceOf(SomeClass.class))</code>.
88+
* <p/>
89+
* For example:
90+
* <pre>assertThat(cheese, isA(Cheddar.class))</pre>
91+
* instead of:
92+
* <pre>assertThat(cheese, is(instanceOf(Cheddar.class)))</pre>
93+
*
8394
*/
8495
@Factory
8596
public static <T> Matcher<T> isA(Class<T> type) {

‎hamcrest-core/src/main/java/org/hamcrest/core/IsAnything.java

Lines changed: 5 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -34,17 +34,19 @@ public void describeTo(Description description) {
3434
}
3535

3636
/**
37-
* This matcher always evaluates to true.
37+
* Creates a matcher that always matches, regardless of the examined object.
3838
*/
3939
@Factory
4040
public static Matcher<Object> anything() {
4141
return new IsAnything<Object>();
4242
}
4343

4444
/**
45-
* This matcher always evaluates to true.
45+
* Creates a matcher that always matches, regardless of the examined object, but describes
46+
* itself with the specified {@link String}.
4647
*
47-
* @param description A meaningful string used when describing itself.
48+
* @param description
49+
* a meaningful {@link String} used when describing itself
4850
*/
4951
@Factory
5052
public static Matcher<Object> anything(String description) {

0 commit comments

Comments
 (0)