Improved documentation of new matchers

build.xml

@@ -5,7 +5,7 @@
 	<property name="src" value="src/main/java" />
 	<property name="target" location="target" />
 	<property name="bin" location="${target}/main" />
-	<property name="version" value="4.7-SNAPSHOT-20090529-1159" />
+	<property name="version" value="4.7-SNAPSHOT-20090601-1258" />
 	<property name="dist" value="junit${version}" />
 	<property name="versionfile" value="${src}/junit/runner/Version.java" />
 	<property name="zipfile"  value="${dist}/${dist}.zip" />

doc/ReleaseNotes4.7.txt

@@ -116,17 +116,25 @@
   - Some matchers have slightly changed type signatures, especially those created
     by `is()` and `equalTo`.  Everything should work, except see `BothTest` for an
     example of how the `both().and()` and `either().or()` constructs may be
-    affected
+    affected.  To essentially disable type-checking for a matcher expression,
+    use `JUnitMatchers.matches()` (see below)
+
+  - `JUnitMatchers.isOneOf(...)` is sugar for the situation where you want to specify
+	a finite list of concrete objects that can match.  For example:
+
+	  assertThat(3, isOneOf(3, 4));
 
-Expected: (is an instance of java.lang.Integer)\n     but: \"actual\" is a java.lang.String
-      @SuppressWarnings("unchecked")
-      public void testMismatchDescriptionDescribesFirstFailingMatch() {
-    	  assertThat("bad speling", 
-    	             allOf(containsString("bad"), containsString("spelling")));
-    	  // prints: Expected: (contains string "bad" and contains string "spelling")
-    	             but: contains string "spelling" was "bad speling"
-	  }
+  - `JUnitMatchers.matches()` disables type-checking of a matcher entirely.
 
+	 Goofy example:
+
+	    assertThat(3, matches(containsString("a")));
+
+	 Real example:
+
+	    assertThat(3, either(matches(is(String.class))).or(
+		                     matches(is(Integer.class))));
+
 ### Docs ###
 - Javadocs now link to online JDK javadocs (bug 2090230)
 - Parameterized runner javadocs improved (bug 2186792)

src/main/java/junit/runner/Version.java

@@ -9,7 +9,7 @@ private Version() {
 	}
 
 	public static String id() {
-		return "4.7-SNAPSHOT-20090529-1159";
+		return "4.7-SNAPSHOT-20090601-1258";
 	}
 
 	public static void main(String[] args) {

src/main/java/org/junit/matchers/JUnitMatchers.java

@@ -15,7 +15,6 @@
  * not currently included in the basic CoreMatchers class from hamcrest.
  */
 public class JUnitMatchers {
-	// TODO (May 27, 2009 11:46:27 AM): deprecate all?
 	/**
 	 * @param element
 	 * @return A matcher matching any collection containing element
@@ -102,10 +101,13 @@ public static <T> CombinableMatcher<T> either(Matcher<T> matcher) {
 	}
 
 	/**
-	 * This is sugar for the situation where 
+	 * This is sugar for the situation where you want to specify
+	 * a finite list of concrete objects that can match.
 	 * For example:
 	 * <pre>
-	 *   assertThat(string, eitherIs("a").or(is("b")));
+	 *   assertThat(string, isOneOf("a", "b", "c"));
+	 *   // is equivalent to
+	 *   assertThat(string, anyOf(is("a"), is("b"), is("c")))
 	 * </pre>
 	 */
 	public static <T> Matcher<T> isOneOf(T... objects) {
@@ -118,7 +120,7 @@ public static <T> Matcher<T> isOneOf(T... objects) {
 
 	/**
 	 * Loosens type parameter, in order to use a Matcher 
-	 * in a place where Java doesn't want to typecheck:
+	 * in a place where Java doesn't want to type-check:
 	 *
 	 * Goofy example:
 	 * <pre>

src/test/java/org/junit/tests/assertion/AssertionTest.java

@@ -10,9 +10,7 @@
 import static org.junit.Assert.fail;
 import static org.junit.matchers.JUnitMatchers.matches;
 
-import java.io.Serializable;
 import java.math.BigDecimal;
-import java.util.Map;
 
 import org.junit.Assert;
 import org.junit.ComparisonFailure;