Hamcrest library that provides Matchers used in Junit assertThat feature has interesting technique for documentation.
If you try to create new custom matcher by implementing Matcher interface you will also need to implement this method:
void dont_implement_Matcher_instead_extend_BaseMatcher()
Seems to be more effective than Javadocs
Add Comment