The interface uses matches(Object) because we don't want to over-restrict how a Matcher is used. We don't necessarily want to bind together where the matcher and matchee are declared. This is equivalent to the equals(Object) method on Object, which obviously could be parameterised but isn't. When experimenting with alternatives, we found that there's a usability problem with generics in practice which can lead to lots of tedious type declarations that add little to the effectiveness of a match.

I appreciate your contribution, but I suggest not making assumptions about the authors' understanding.

Thanks

Thanks for your quick feedback.

I appreciate your contribution, but I suggest not making assumptions about the authors' understanding.

Then you should write that explanation in the Javadoc comment instead of one that leaves the reader with that impression about the understanding of the author. Especially the finding on use cases where this design has advantages should definitely be listed there because it's very helpful at this location (in case you have it somewhere else, please add a link instead).

The interface uses matches(Object) because we don't want to over-restrict how a Matcher is used. We don't necessarily want to bind together where the matcher and matchee are declared. This is equivalent to the equals(Object) method on Object, which obviously could be parameterised but isn't. When experimenting with alternatives, we found that there's a usability problem with generics in practice which can lead to lots of tedious type declarations that add little to the effectiveness of a match.

The idea of generics is to avoid casting and eventual exceptions - not so much for the sake of effectiveness, but type-safety and static analysis - the code becomes more effective because it's a lot easier to maintain, not in an algorithmic runtime-oriented sense. Like I explained, the changes have no downside and don't add any overhead for users which want to use Matcher instead of Matcher<T>, but allow user who wish to write type-safe code - which implies the necessary overhead; e.g. the missing feature to call static methods with type parameter is a real bummer in Java since having to write Matcher.<String>any() instead of any() can be tedious indeed, however it's not necessary.

In order to be able to apply the same argument for Matcher that is used for Object.equals you would have to remove the type parameter because it's unused, I think, but it's a good point - however, Object.equals is special for many reasons that don't apply to Matcher.matches.

For what it's worth, I'm using hamkrest for projects which I migrated to Kotlin already which solves the problem I was trying to solve here.