Repository: mockito/mockito
Issue: Either revert recent Functional Interfaces change or change JavaDoc

I've been reading the Javadoc regarding `ArgumentMatcher` and I noticed a couple of things. Relating back to the changes of #338 
- The example of how to override it is still based around `Object` rather than `T`
- Someone has very deliberately decided not to make it use `T` in the past and now we've changed that.

> The argument is not using the generic type in order to force explicit casting in the implementation. This way it is easier to debug when incompatible arguments are passed to the matchers. You have to trust us on this one. If we used parametrized type then ClassCastException would be thrown in certain scenarios.

My view at the time was that changing it to `T` would remove the class casting and that this would be a good thing. It was kind of necessary to have it as `T` so that the lambda expressions in Java 8 could infer the right types.

The rationale about a class cast exception giving weird results kind of makes sense, but does that really really happen? It seems it's either solve one problem or the other.

What do folks think? I'll happily amend the code either way.


Issue comments:
I can't imagine a scenario where the parameterized type cause problems and why it aids debuging if no type parameter is used.

@all Do we have examples that illustrate the described problem? If not the JavaDoc should be removed!

#454 is one way we could wrap this up. Sorry for not noticing it sooner!

If we receive such a report, we should catch such an exception and log an appropriate error why this is happening. For now I can't see this breaking, but I am happy to be proven wrong.


Pull request review comments:

Patch that resolved the issue:
diff --git a/src/main/java/org/mockito/ArgumentMatcher.java b/src/main/java/org/mockito/ArgumentMatcher.java
index 3b2e3d19c4..8b9abd0ce4 100644
--- a/src/main/java/org/mockito/ArgumentMatcher.java
+++ b/src/main/java/org/mockito/ArgumentMatcher.java
@@ -35,6 +35,8 @@
  *     Useful if you already have a hamcrest matcher. Reuse and win!
  *     Note that {@link org.mockito.hamcrest.MockitoHamcrest#argThat(org.hamcrest.Matcher)} demonstrates <b>NullPointerException</b> auto-unboxing caveat.
  *     </li>
+ *     <li>Java 8 only - use a lambda in place of an {@link ArgumentMatcher} since {@link ArgumentMatcher}
+ *     is effectively a functional interface. A lambda can be used with the {@link Mockito#argThat} method.</li>
  * </ul>
  *
  * <p>
@@ -44,8 +46,8 @@
  *
  * <pre class="code"><code class="java">
  * class ListOfTwoElements implements ArgumentMatcher&lt;List&gt; {
- *     public boolean matches(Object list) {
- *         return ((List) list).size() == 2;
+ *     public boolean matches(List list) {
+ *         return list.size() == 2;
  *     }
  *     public String toString() {
  *         //printed in verification errors
@@ -93,6 +95,7 @@
  * b) Use <code>org.mockito.hamcrest.MockitoHamcrest.argThat()</code> instead of <code>Mockito.argThat()</code>.
  * Ensure that there is <a href="http://hamcrest.org/JavaHamcrest/">hamcrest</a> dependency on classpath
  * (Mockito does not depend on hamcrest any more).
+ *
  * </li>
  * </ul>
  * What option is right for you? If you don't mind compile dependency to hamcrest
@@ -111,22 +114,6 @@ public interface ArgumentMatcher<T> {
      * The method should <b>never</b> assert if the argument doesn't match. It
      * should only return false.
      * <p>
-     * The argument is not using the generic type in order to force explicit casting in the implementation.
-     * This way it is easier to debug when incompatible arguments are passed to the matchers.
-     * You have to trust us on this one. If we used parametrized type then <code>ClassCastException</code>
-     * would be thrown in certain scenarios.
-     * For example:
-     *
-     * <pre class="code"><code class="java">
-     *   //test, method accepts Collection argument and ArgumentMatcher&lt;List&gt; is used
-     *   when(mock.useCollection(someListMatcher())).thenDoNothing();
-     *
-     *   //production code, yields confusing ClassCastException
-     *   //although Set extends Collection but is not compatible with ArgumentMatcher&lt;List&gt;
-     *   mock.useCollection(new HashSet());
-     * </pre>
-     *
-     * <p>
      * See the example in the top level javadoc for {@link ArgumentMatcher}
      *
      * @param argument


Test patch: