Allow "normal" objects to describe themself, e.g. in case of a mismatch

[PirolA]

Motivation
I needed to give detailed descriptions of an object in case of a mismatch and couldn't use toString().

Solution

• Use the existing SelfDescribing Interface and retrieve a description based on its describeTo method.

[sf105]

What is the situation where you can't use the appendDescriptionOf method?

[PirolA]

If I remember correctly, this only works for matchers, but not for POJOs, right?

Roughly speaking, my problem occured when calling assertThat(somePOJO, equalsTo(anotherPOJO)) and equalsTo() is using some information, that's not exposed by the toString() method. Then - in case of a mismatch - an insufficient error message is printed. As a "workaround" for this I used the mechanism in this PR.

[tumbarumba]

This change seems like an improvement. @PirolA, can you add a test for the changed functionality to this PR?

[panchenko]

There is a fundamental problem with this approach: normally hamcrest would be a test dependency.

[nhojpatrick]

@PirolA interesting idea, as some previous comments have highlights it would mean hamcrest being a non compile dependency. maybe looking at how spotbugsfindbugs have spotbugs-annotations/findbugs-annotations, where we could support something like thats a making a lightweight runtime jar if you really needed.

please can you rebase from master, as hamcrest-core and hamcrest-library have been refactored a lot and also deprecated, so that everything is just in hamcrest.

[nhojpatrick]

Going to try and kick start hamcrest, so if you want to get it merged, please rebase from the branch v2.3-candidates.
Still trying to understand how has permissions to perform a release.