diff --git a/hamcrest-integration/src/main/java/org/hamcrest/integration/EasyMock2Adapter.java b/hamcrest-integration/src/main/java/org/hamcrest/integration/EasyMock2Adapter.java
index 09ab0f7d..d5ce5257 100644
--- a/hamcrest-integration/src/main/java/org/hamcrest/integration/EasyMock2Adapter.java
+++ b/hamcrest-integration/src/main/java/org/hamcrest/integration/EasyMock2Adapter.java
@@ -18,6 +18,8 @@ public class EasyMock2Adapter implements IArgumentMatcher {
      * Hamcrest {@link org.hamcrest.Matcher} to act as an
      * EasyMock {@link org.easymock.IArgumentMatcher} and
      * report it to EasyMock so it can be kept track of.
+     *
+     * @return The EasyMock matcher.
      */
     public static IArgumentMatcher adapt(Matcher<?> matcher) {
         EasyMock2Adapter easyMock2Matcher = new EasyMock2Adapter(matcher);
diff --git a/hamcrest-integration/src/main/java/org/hamcrest/integration/JMock1Adapter.java b/hamcrest-integration/src/main/java/org/hamcrest/integration/JMock1Adapter.java
index fa2021ce..168d79b9 100644
--- a/hamcrest-integration/src/main/java/org/hamcrest/integration/JMock1Adapter.java
+++ b/hamcrest-integration/src/main/java/org/hamcrest/integration/JMock1Adapter.java
@@ -18,6 +18,8 @@ public class JMock1Adapter implements Constraint {
      * Convenience factory method that will adapt a
      * Hamcrest {@link org.hamcrest.Matcher} to act as an
      * jMock {@link org.jmock.core.Constraint}.
+     *
+     * @return The jMock constraint.
      */
     public static Constraint adapt(Matcher<?> matcher) {
         return new JMock1Adapter(matcher);
diff --git a/hamcrest/src/main/java/org/hamcrest/TypeSafeDiagnosingMatcher.java b/hamcrest/src/main/java/org/hamcrest/TypeSafeDiagnosingMatcher.java
index 03efa9db..b13c1d4b 100644
--- a/hamcrest/src/main/java/org/hamcrest/TypeSafeDiagnosingMatcher.java
+++ b/hamcrest/src/main/java/org/hamcrest/TypeSafeDiagnosingMatcher.java
@@ -21,6 +21,8 @@ public abstract class TypeSafeDiagnosingMatcher<T> extends BaseMatcher<T> {
     /**
      * Subclasses should implement this. The item will already have been checked
      * for the specific type and will never be null.
+     *
+     * @return boolean true/false depending if item matches matcher.
      */
     protected abstract boolean matchesSafely(T item, Description mismatchDescription);
 
diff --git a/hamcrest/src/main/java/org/hamcrest/TypeSafeMatcher.java b/hamcrest/src/main/java/org/hamcrest/TypeSafeMatcher.java
index 08dfce8b..ed7b08e3 100644
--- a/hamcrest/src/main/java/org/hamcrest/TypeSafeMatcher.java
+++ b/hamcrest/src/main/java/org/hamcrest/TypeSafeMatcher.java
@@ -43,6 +43,8 @@ protected TypeSafeMatcher(ReflectiveTypeFinder typeFinder) {
     /**
      * Subclasses should implement this. The item will already have been checked for
      * the specific type and will never be null.
+     *
+     * @return boolean true/false depending if item matches matcher.
      */
     protected abstract boolean matchesSafely(T item);
     
diff --git a/hamcrest/src/main/java/org/hamcrest/beans/HasProperty.java b/hamcrest/src/main/java/org/hamcrest/beans/HasProperty.java
index 7f2f2687..3a7cfe65 100644
--- a/hamcrest/src/main/java/org/hamcrest/beans/HasProperty.java
+++ b/hamcrest/src/main/java/org/hamcrest/beans/HasProperty.java
@@ -48,6 +48,7 @@ public void describeTo(Description description) {
      *
      * @param propertyName
      *     the name of the JavaBean property that examined beans should possess
+     * @return The matcher.
      */
     public static <T> Matcher<T> hasProperty(String propertyName) {
         return new HasProperty<T>(propertyName);
diff --git a/hamcrest/src/main/java/org/hamcrest/beans/HasPropertyWithValue.java b/hamcrest/src/main/java/org/hamcrest/beans/HasPropertyWithValue.java
index b9e33d22..1bf81dec 100644
--- a/hamcrest/src/main/java/org/hamcrest/beans/HasPropertyWithValue.java
+++ b/hamcrest/src/main/java/org/hamcrest/beans/HasPropertyWithValue.java
@@ -159,6 +159,7 @@ public Condition<Method> apply(PropertyDescriptor property, Description mismatch
      *     the name of the JavaBean property that examined beans should possess
      * @param valueMatcher
      *     a matcher for the value of the specified property of the examined bean
+     * @return The matcher.
      */
     public static <T> Matcher<T> hasProperty(String propertyName, Matcher<?> valueMatcher) {
         return new HasPropertyWithValue<>(propertyName, valueMatcher);
@@ -176,6 +177,7 @@ public static <T> Matcher<T> hasProperty(String propertyName, Matcher<?> valueMa
      *     the dot-separated path from the examined object to the JavaBean property
      * @param valueMatcher
      *     a matcher for the value of the specified property of the examined bean
+     * @return The matcher.
      */
     public static <T> Matcher<T> hasPropertyAtPath(String path, Matcher<T> valueMatcher) {
         List<String> properties = Arrays.asList(path.split("\\."));
diff --git a/hamcrest/src/main/java/org/hamcrest/beans/SamePropertyValuesAs.java b/hamcrest/src/main/java/org/hamcrest/beans/SamePropertyValuesAs.java
index 4799aeaa..c36203f7 100644
--- a/hamcrest/src/main/java/org/hamcrest/beans/SamePropertyValuesAs.java
+++ b/hamcrest/src/main/java/org/hamcrest/beans/SamePropertyValuesAs.java
@@ -151,6 +151,7 @@ private static Object readProperty(Method method, Object target) {
      *     the bean against which examined beans are compared
      * @param ignoredProperties
      *     do not check any of these named properties.
+     * @return The matcher.
      */
     public static <B> Matcher<B> samePropertyValuesAs(B expectedBean, String... ignoredProperties) {
         return new SamePropertyValuesAs<>(expectedBean, asList(ignoredProperties));
diff --git a/hamcrest/src/main/java/org/hamcrest/collection/ArrayMatching.java b/hamcrest/src/main/java/org/hamcrest/collection/ArrayMatching.java
index fc968e0b..d6adc224 100644
--- a/hamcrest/src/main/java/org/hamcrest/collection/ArrayMatching.java
+++ b/hamcrest/src/main/java/org/hamcrest/collection/ArrayMatching.java
@@ -26,6 +26,7 @@ public class ArrayMatching {
    *
    * @param elementMatcher
    *     the matcher to apply to elements in examined arrays
+   * @return The matcher.
    */
   public static <T> Matcher<T[]> hasItemInArray(Matcher<? super T> elementMatcher) {
       return new HasItemInArray<>(elementMatcher);
@@ -40,6 +41,7 @@ public static <T> Matcher<T[]> hasItemInArray(Matcher<? super T> elementMatcher)
    *
    * @param element
    *     the element that should be present in examined arrays
+   * @return The matcher.
    */
   public static <T> Matcher<T[]> hasItemInArray(T element) {
     return hasItemInArray(equalTo(element));
@@ -64,6 +66,7 @@ public static <T> Matcher<T[]> hasItemInArray(T element) {
    *
    * @param itemMatchers
    *     a list of matchers, each of which must be satisfied by an entry in an examined array
+   * @return The matcher.
    */
   @SafeVarargs
   public static <E> Matcher<E[]> arrayContainingInAnyOrder(Matcher<? super E>... itemMatchers) {
@@ -89,6 +92,7 @@ public static <E> Matcher<E[]> arrayContainingInAnyOrder(Matcher<? super E>... i
    *
    * @param itemMatchers
    *     a list of matchers, each of which must be satisfied by an item provided by an examined array
+   * @return The matcher.
    */
   public static <E> Matcher<E[]> arrayContainingInAnyOrder(Collection<Matcher<? super E>> itemMatchers) {
     return new ArrayAsIterableMatcher<>(new IsIterableContainingInAnyOrder<>(itemMatchers), itemMatchers, "in any order");
@@ -111,6 +115,7 @@ public static <E> Matcher<E[]> arrayContainingInAnyOrder(Collection<Matcher<? su
    *
    * @param items
    *     the items that must equal the entries of an examined array, in any order
+   * @return The matcher.
    */
   @SafeVarargs
   public static <E> Matcher<E[]> arrayContainingInAnyOrder(E... items) {
@@ -126,6 +131,7 @@ public static <E> Matcher<E[]> arrayContainingInAnyOrder(E... items) {
    *
    * @param items
    *     the items that must equal the items within an examined array
+   * @return The matcher.
    */
   @SafeVarargs
   public static <E> Matcher<E[]> arrayContaining(E... items) {
@@ -140,6 +146,7 @@ public static <E> Matcher<E[]> arrayContaining(E... items) {
    *
    * @param itemMatchers
    *     the matchers that must be satisfied by the items in the examined array
+   * @return The matcher.
    */
   @SafeVarargs
   public static <E> Matcher<E[]> arrayContaining(Matcher<? super E>... itemMatchers) {
@@ -159,6 +166,7 @@ public static <E> Matcher<E[]> arrayContaining(Matcher<? super E>... itemMatcher
    *
    * @param itemMatchers
    *     a list of matchers, each of which must be satisfied by the corresponding item in an examined array
+   * @return The matcher.
    */
   public static <E> Matcher<E[]> arrayContaining(List<Matcher<? super E>> itemMatchers) {
       return new ArrayAsIterableMatcher<>(new IsIterableContainingInOrder<>(itemMatchers), itemMatchers, "");
diff --git a/hamcrest/src/main/java/org/hamcrest/collection/IsArray.java b/hamcrest/src/main/java/org/hamcrest/collection/IsArray.java
index 8fbd93b4..22fef90a 100644
--- a/hamcrest/src/main/java/org/hamcrest/collection/IsArray.java
+++ b/hamcrest/src/main/java/org/hamcrest/collection/IsArray.java
@@ -55,6 +55,8 @@ public void describeTo(Description description) {
      *
      * Can be overridden in subclasses to customise how the matcher is
      * described.
+     *
+     * @return The description prefix.
      */
     protected String descriptionStart() {
         return "[";
@@ -65,6 +67,8 @@ protected String descriptionStart() {
      *
      * Can be overridden in subclasses to customise how the matcher is
      * described.
+     *
+     * @return The description separator.
      */
     protected String descriptionSeparator() {
         return ", ";
@@ -75,6 +79,8 @@ protected String descriptionSeparator() {
      *
      * Can be overridden in subclasses to customise how the matcher is
      * described.
+     *
+     * @return The description suffix.
      */
     protected String descriptionEnd() {
         return "]";
@@ -89,6 +95,7 @@ protected String descriptionEnd() {
      *
      * @param elementMatchers
      *     the matchers that the elements of examined arrays should satisfy
+     * @return The matcher.
      */
     public static <T> IsArray<T> array(Matcher<? super T>... elementMatchers) {
         return new IsArray<T>(elementMatchers);
diff --git a/hamcrest/src/main/java/org/hamcrest/collection/IsArrayContainingInAnyOrder.java b/hamcrest/src/main/java/org/hamcrest/collection/IsArrayContainingInAnyOrder.java
index 7e72a622..3157bcce 100644
--- a/hamcrest/src/main/java/org/hamcrest/collection/IsArrayContainingInAnyOrder.java
+++ b/hamcrest/src/main/java/org/hamcrest/collection/IsArrayContainingInAnyOrder.java
@@ -57,6 +57,7 @@ public void describeTo(Description description) {
      *
      * @param itemMatchers
      *     a list of matchers, each of which must be satisfied by an entry in an examined array
+     * @return The matcher.
      */
     public static <E> Matcher<E[]> arrayContainingInAnyOrder(Matcher<? super E>... itemMatchers) {
         return arrayContainingInAnyOrder(Arrays.asList(itemMatchers));
@@ -79,6 +80,7 @@ public static <E> Matcher<E[]> arrayContainingInAnyOrder(Matcher<? super E>... i
      *
      * @param itemMatchers
      *     a list of matchers, each of which must be satisfied by an item provided by an examined array
+     * @return The matcher.
      */
     public static <E> Matcher<E[]> arrayContainingInAnyOrder(Collection<Matcher<? super E>> itemMatchers) {
         return new IsArrayContainingInAnyOrder<E>(itemMatchers);
@@ -101,6 +103,7 @@ public static <E> Matcher<E[]> arrayContainingInAnyOrder(Collection<Matcher<? su
      *
      * @param items
      *     the items that must equal the entries of an examined array, in any order
+     * @return The matcher.
      */
     public static <E> Matcher<E[]> arrayContainingInAnyOrder(E... items) {
       List<Matcher<? super E>> matchers = new ArrayList<Matcher<? super E>>();
diff --git a/hamcrest/src/main/java/org/hamcrest/collection/IsArrayContainingInOrder.java b/hamcrest/src/main/java/org/hamcrest/collection/IsArrayContainingInOrder.java
index c046914f..e26cc462 100644
--- a/hamcrest/src/main/java/org/hamcrest/collection/IsArrayContainingInOrder.java
+++ b/hamcrest/src/main/java/org/hamcrest/collection/IsArrayContainingInOrder.java
@@ -50,6 +50,7 @@ public void describeTo(Description description) {
      *
      * @param items
      *     the items that must equal the items within an examined array
+     * @return The matcher.
      */
     public static <E> Matcher<E[]> arrayContaining(E... items) {
         List<Matcher<? super E>> matchers = new ArrayList<Matcher<? super E>>();
@@ -71,6 +72,7 @@ public static <E> Matcher<E[]> arrayContaining(E... items) {
      *
      * @param itemMatchers
      *     the matchers that must be satisfied by the items in the examined array
+     * @return The matcher.
      */
     public static <E> Matcher<E[]> arrayContaining(Matcher<? super E>... itemMatchers) {
         return arrayContaining(asList(itemMatchers));
@@ -88,6 +90,7 @@ public static <E> Matcher<E[]> arrayContaining(Matcher<? super E>... itemMatcher
      *
      * @param itemMatchers
      *     a list of matchers, each of which must be satisfied by the corresponding item in an examined array
+     * @return The matcher.
      */
     public static <E> Matcher<E[]> arrayContaining(List<Matcher<? super E>> itemMatchers) {
         return new IsArrayContainingInOrder<E>(itemMatchers);
diff --git a/hamcrest/src/main/java/org/hamcrest/collection/IsArrayWithSize.java b/hamcrest/src/main/java/org/hamcrest/collection/IsArrayWithSize.java
index 14695a67..d779691f 100644
--- a/hamcrest/src/main/java/org/hamcrest/collection/IsArrayWithSize.java
+++ b/hamcrest/src/main/java/org/hamcrest/collection/IsArrayWithSize.java
@@ -27,6 +27,7 @@ protected Integer featureValueOf(E[] actual) {
      *
      * @param sizeMatcher
      *     a matcher for the length of an examined array
+     * @return The matcher.
      */
     public static <E> Matcher<E[]> arrayWithSize(Matcher<? super Integer> sizeMatcher) {
         return new IsArrayWithSize<>(sizeMatcher);
@@ -40,6 +41,7 @@ public static <E> Matcher<E[]> arrayWithSize(Matcher<? super Integer> sizeMatche
      *
      * @param size
      *     the length that an examined array must have for a positive match
+     * @return The matcher.
      */
     public static <E> Matcher<E[]> arrayWithSize(int size) {
         return arrayWithSize(equalTo(size));
@@ -50,6 +52,8 @@ public static <E> Matcher<E[]> arrayWithSize(int size) {
      * is zero.
      * For example:
      * <pre>assertThat(new String[0], emptyArray())</pre>
+     *
+     * @return The matcher.
      */
     public static <E> Matcher<E[]> emptyArray() {
         return describedAs("an empty array", IsArrayWithSize.<E>arrayWithSize(0));
diff --git a/hamcrest/src/main/java/org/hamcrest/collection/IsCollectionWithSize.java b/hamcrest/src/main/java/org/hamcrest/collection/IsCollectionWithSize.java
index ccb3798e..8ff37131 100644
--- a/hamcrest/src/main/java/org/hamcrest/collection/IsCollectionWithSize.java
+++ b/hamcrest/src/main/java/org/hamcrest/collection/IsCollectionWithSize.java
@@ -28,6 +28,7 @@ protected Integer featureValueOf(Collection<? extends E> actual) {
      *
      * @param sizeMatcher
      *     a matcher for the size of an examined {@link java.util.Collection}
+     * @return The matcher.
      */
     public static <E> Matcher<Collection<? extends E>> hasSize(Matcher<? super Integer> sizeMatcher) {
         return new IsCollectionWithSize<E>(sizeMatcher);
@@ -41,6 +42,7 @@ public static <E> Matcher<Collection<? extends E>> hasSize(Matcher<? super Integ
      *
      * @param size
      *     the expected size of an examined {@link java.util.Collection}
+     * @return The matcher.
      */
     @SuppressWarnings({ "rawtypes", "unchecked" })
     public static <E> Matcher<Collection<? extends E>> hasSize(int size) {
diff --git a/hamcrest/src/main/java/org/hamcrest/collection/IsEmptyCollection.java b/hamcrest/src/main/java/org/hamcrest/collection/IsEmptyCollection.java
index 217c9682..c48b80e5 100644
--- a/hamcrest/src/main/java/org/hamcrest/collection/IsEmptyCollection.java
+++ b/hamcrest/src/main/java/org/hamcrest/collection/IsEmptyCollection.java
@@ -31,6 +31,8 @@ public void describeTo(Description description) {
      * method returns <code>true</code>.
      * For example:
      * <pre>assertThat(new ArrayList&lt;String&gt;(), is(empty()))</pre>
+     *
+     * @return The matcher.
      */
     public static <E> Matcher<Collection<? extends E>> empty() {
         return new IsEmptyCollection<E>();
@@ -44,6 +46,7 @@ public static <E> Matcher<Collection<? extends E>> empty() {
      *
      * @param unusedToForceReturnType
      *     the type of the collection's content
+     * @return The matcher.
      */
     @SuppressWarnings({"unchecked", "UnusedParameters"})
     public static <E> Matcher<Collection<E>> emptyCollectionOf(Class<E> unusedToForceReturnType) {
diff --git a/hamcrest/src/main/java/org/hamcrest/collection/IsEmptyIterable.java b/hamcrest/src/main/java/org/hamcrest/collection/IsEmptyIterable.java
index 9900ebd3..fc1f5a3d 100644
--- a/hamcrest/src/main/java/org/hamcrest/collection/IsEmptyIterable.java
+++ b/hamcrest/src/main/java/org/hamcrest/collection/IsEmptyIterable.java
@@ -27,6 +27,8 @@ public void describeTo(Description description) {
      * Creates a matcher for {@link Iterable}s matching examined iterables that yield no items.
      * For example:
      * <pre>assertThat(new ArrayList&lt;String&gt;(), is(emptyIterable()))</pre>
+     *
+     * @return The matcher.
      */
     public static <E> Matcher<Iterable<? extends E>> emptyIterable() {
         return new IsEmptyIterable<E>();
@@ -39,6 +41,7 @@ public static <E> Matcher<Iterable<? extends E>> emptyIterable() {
      *
      * @param unusedToForceReturnType
      *     the type of the iterable's content
+     * @return The matcher.
      */
     @SuppressWarnings({"unchecked", "UnusedParameters"})
     public static <E> Matcher<Iterable<E>> emptyIterableOf(Class<E> unusedToForceReturnType) {
diff --git a/hamcrest/src/main/java/org/hamcrest/collection/IsIn.java b/hamcrest/src/main/java/org/hamcrest/collection/IsIn.java
index aa133013..b9b74571 100644
--- a/hamcrest/src/main/java/org/hamcrest/collection/IsIn.java
+++ b/hamcrest/src/main/java/org/hamcrest/collection/IsIn.java
@@ -40,6 +40,7 @@ public void describeTo(Description buffer) {
      *
      * @param collection
      *     the collection in which matching items must be found
+     * @return The matcher.
      */
     @Deprecated
     public static <T> Matcher<T> isIn(Collection<T> collection) {
@@ -54,6 +55,7 @@ public static <T> Matcher<T> isIn(Collection<T> collection) {
      *
      * @param collection
      *     the collection in which matching items must be found
+     * @return The matcher.
      */
     public static <T> Matcher<T> in(Collection<T> collection) {
         return new IsIn<>(collection);
@@ -69,6 +71,7 @@ public static <T> Matcher<T> in(Collection<T> collection) {
      *
      * @param elements
      *     the array in which matching items must be found
+     * @return The matcher.
      */
     @Deprecated
     public static <T> Matcher<T> isIn(T[] elements) {
@@ -83,6 +86,7 @@ public static <T> Matcher<T> isIn(T[] elements) {
      *
      * @param elements
      *     the array in which matching items must be found
+     * @return The matcher.
      */
     public static <T> Matcher<T> in(T[] elements) {
         return new IsIn<>(elements);
@@ -97,7 +101,8 @@ public static <T> Matcher<T> in(T[] elements) {
      * @deprecated use is(oneOf(...)) instead
      *
      * @param elements
-     *     the elements amongst which matching items will be found 
+     *     the elements amongst which matching items will be found
+     * @return The matcher.
      */
     @SafeVarargs
     @Deprecated
@@ -112,7 +117,8 @@ public static <T> Matcher<T> isOneOf(T... elements) {
      * <pre>assertThat("foo", is(oneOf("bar", "foo")))</pre>
      *
      * @param elements
-     *     the elements amongst which matching items will be found 
+     *     the elements amongst which matching items will be found
+     * @return The matcher.
      */
     @SafeVarargs
     public static <T> Matcher<T> oneOf(T... elements) {
diff --git a/hamcrest/src/main/java/org/hamcrest/collection/IsIterableContainingInAnyOrder.java b/hamcrest/src/main/java/org/hamcrest/collection/IsIterableContainingInAnyOrder.java
index c9ea7964..daaf9277 100644
--- a/hamcrest/src/main/java/org/hamcrest/collection/IsIterableContainingInAnyOrder.java
+++ b/hamcrest/src/main/java/org/hamcrest/collection/IsIterableContainingInAnyOrder.java
@@ -95,6 +95,7 @@ private boolean isMatched(S item) {
      *
      * @param itemMatchers
      *     a list of matchers, each of which must be satisfied by an item provided by an examined {@link Iterable}
+     * @return The matcher.
      */
     @SafeVarargs
     public static <T> Matcher<Iterable<? extends T>> containsInAnyOrder(Matcher<? super T>... itemMatchers) {
@@ -120,6 +121,7 @@ public static <T> Matcher<Iterable<? extends T>> containsInAnyOrder(Matcher<? su
      *
      * @param items
      *     the items that must equal the items provided by an examined {@link Iterable} in any order
+     * @return The matcher.
      */
     @SafeVarargs
     public static <T> Matcher<Iterable<? extends T>> containsInAnyOrder(T... items) {
@@ -148,6 +150,7 @@ public static <T> Matcher<Iterable<? extends T>> containsInAnyOrder(T... items)
      *
      * @param itemMatchers
      *     a list of matchers, each of which must be satisfied by an item provided by an examined {@link Iterable}
+     * @return The matcher.
      */
     public static <T> Matcher<Iterable<? extends T>> containsInAnyOrder(Collection<Matcher<? super T>> itemMatchers) {
         return new IsIterableContainingInAnyOrder<>(itemMatchers);
diff --git a/hamcrest/src/main/java/org/hamcrest/collection/IsIterableContainingInOrder.java b/hamcrest/src/main/java/org/hamcrest/collection/IsIterableContainingInOrder.java
index ee6b04c3..5f30d379 100644
--- a/hamcrest/src/main/java/org/hamcrest/collection/IsIterableContainingInOrder.java
+++ b/hamcrest/src/main/java/org/hamcrest/collection/IsIterableContainingInOrder.java
@@ -91,6 +91,7 @@ private void describeMismatch(Matcher<? super F> matcher, F item) {
      *
      * @param items
      *     the items that must equal the items provided by an examined {@link Iterable}
+     * @return The matcher.
      */
     @SafeVarargs
     public static <E> Matcher<Iterable<? extends E>> contains(E... items) {
@@ -107,6 +108,7 @@ public static <E> Matcher<Iterable<? extends E>> contains(E... items) {
      * @param itemMatcher
      *     the matcher that must be satisfied by the single item provided by an
      *     examined {@link Iterable}
+     * @return The matcher.
      */
     @SuppressWarnings("unchecked")
     public static <E> Matcher<Iterable<? extends E>> contains(final Matcher<? super E> itemMatcher) {
@@ -123,6 +125,7 @@ public static <E> Matcher<Iterable<? extends E>> contains(final Matcher<? super
      *
      * @param itemMatchers
      *     the matchers that must be satisfied by the items provided by an examined {@link Iterable}
+     * @return The matcher.
      */
     @SafeVarargs
     public static <E> Matcher<Iterable<? extends E>> contains(Matcher<? super E>... itemMatchers) {
@@ -143,6 +146,7 @@ public static <E> Matcher<Iterable<? extends E>> contains(Matcher<? super E>...
      * @param itemMatchers
      *     a list of matchers, each of which must be satisfied by the corresponding item provided by
      *     an examined {@link Iterable}
+     * @return The matcher.
      */
     public static <E> Matcher<Iterable<? extends E>> contains(List<Matcher<? super E>> itemMatchers) {
         return new IsIterableContainingInOrder<>(itemMatchers);
diff --git a/hamcrest/src/main/java/org/hamcrest/collection/IsIterableContainingInRelativeOrder.java b/hamcrest/src/main/java/org/hamcrest/collection/IsIterableContainingInRelativeOrder.java
index 31ae8d94..9a505516 100644
--- a/hamcrest/src/main/java/org/hamcrest/collection/IsIterableContainingInRelativeOrder.java
+++ b/hamcrest/src/main/java/org/hamcrest/collection/IsIterableContainingInRelativeOrder.java
@@ -76,6 +76,7 @@ public boolean isFinished() {
      *
      * @param items
      *     the items that must be contained within items provided by an examined {@link Iterable} in the same relative order
+     * @return The matcher.
      */
     @SafeVarargs
     public static <E> Matcher<Iterable<? extends E>> containsInRelativeOrder(E... items) {
@@ -96,6 +97,7 @@ public static <E> Matcher<Iterable<? extends E>> containsInRelativeOrder(E... it
      *
      * @param itemMatchers
      *     the matchers that must be satisfied by the items provided by an examined {@link Iterable} in the same relative order
+     * @return The matcher.
      */
     @SafeVarargs
     public static <E> Matcher<Iterable<? extends E>> containsInRelativeOrder(Matcher<? super E>... itemMatchers) {
@@ -112,6 +114,7 @@ public static <E> Matcher<Iterable<? extends E>> containsInRelativeOrder(Matcher
      * @param itemMatchers
      *     a list of matchers, each of which must be satisfied by the items provided by
      *     an examined {@link Iterable} in the same relative order
+     * @return The matcher.
      */
     public static <E> Matcher<Iterable<? extends E>> containsInRelativeOrder(List<Matcher<? super E>> itemMatchers) {
         return new IsIterableContainingInRelativeOrder<>(itemMatchers);
diff --git a/hamcrest/src/main/java/org/hamcrest/collection/IsIterableWithSize.java b/hamcrest/src/main/java/org/hamcrest/collection/IsIterableWithSize.java
index 7c79e746..9d2a69c9 100644
--- a/hamcrest/src/main/java/org/hamcrest/collection/IsIterableWithSize.java
+++ b/hamcrest/src/main/java/org/hamcrest/collection/IsIterableWithSize.java
@@ -32,6 +32,7 @@ protected Integer featureValueOf(Iterable<E> actual) {
      *
      * @param sizeMatcher
      *     a matcher for the number of items that should be yielded by an examined {@link Iterable}
+     * @return The matcher.
      */
     public static <E> Matcher<Iterable<E>> iterableWithSize(Matcher<? super Integer> sizeMatcher) {
         return new IsIterableWithSize<E>(sizeMatcher);
@@ -46,6 +47,7 @@ public static <E> Matcher<Iterable<E>> iterableWithSize(Matcher<? super Integer>
      *
      * @param size
      *     the number of items that should be yielded by an examined {@link Iterable}
+     * @return The matcher.
      */
     public static <E> Matcher<Iterable<E>> iterableWithSize(int size) {
         return iterableWithSize(equalTo(size));
diff --git a/hamcrest/src/main/java/org/hamcrest/collection/IsMapContaining.java b/hamcrest/src/main/java/org/hamcrest/collection/IsMapContaining.java
index 72c7899a..130e69c6 100644
--- a/hamcrest/src/main/java/org/hamcrest/collection/IsMapContaining.java
+++ b/hamcrest/src/main/java/org/hamcrest/collection/IsMapContaining.java
@@ -54,6 +54,7 @@ public void describeTo(Description description) {
      *     the key matcher that, in combination with the valueMatcher, must be satisfied by at least one entry
      * @param valueMatcher
      *     the value matcher that, in combination with the keyMatcher, must be satisfied by at least one entry
+     * @return The matcher.
      */
     public static <K,V> Matcher<Map<? extends K,? extends V>> hasEntry(Matcher<? super K> keyMatcher, Matcher<? super V> valueMatcher) {
         return new IsMapContaining<>(keyMatcher, valueMatcher);
@@ -70,6 +71,7 @@ public static <K,V> Matcher<Map<? extends K,? extends V>> hasEntry(Matcher<? sup
      *     the key that, in combination with the value, must be describe at least one entry
      * @param value
      *     the value that, in combination with the key, must be describe at least one entry
+     * @return The matcher.
      */
     public static <K,V> Matcher<Map<? extends K,? extends V>> hasEntry(K key, V value) {
         return new IsMapContaining<>(equalTo(key), equalTo(value));
@@ -83,6 +85,7 @@ public static <K,V> Matcher<Map<? extends K,? extends V>> hasEntry(K key, V valu
      *
      * @param keyMatcher
      *     the matcher that must be satisfied by at least one key
+     * @return The matcher.
      */
     public static <K> Matcher<Map<? extends K, ?>> hasKey(Matcher<? super K> keyMatcher) {
         return new IsMapContaining<>(keyMatcher, anything());
@@ -96,6 +99,7 @@ public static <K,V> Matcher<Map<? extends K,? extends V>> hasEntry(K key, V valu
      *
      * @param key
      *     the key that satisfying maps must contain
+     * @return The matcher.
      */
     public static <K> Matcher<Map<? extends K, ?>> hasKey(K key) {
         return new IsMapContaining<>(equalTo(key), anything());
@@ -109,6 +113,7 @@ public static <K,V> Matcher<Map<? extends K,? extends V>> hasEntry(K key, V valu
      *
      * @param valueMatcher
      *     the matcher that must be satisfied by at least one value
+     * @return The matcher.
      */
     public static <V> Matcher<Map<?, ? extends V>> hasValue(Matcher<? super V> valueMatcher) {
         return new IsMapContaining<>(anything(), valueMatcher);
@@ -122,6 +127,7 @@ public static <K,V> Matcher<Map<? extends K,? extends V>> hasEntry(K key, V valu
      *
      * @param value
      *     the value that satisfying maps must contain
+     * @return The matcher.
      */
     public static <V> Matcher<Map<?, ? extends V>> hasValue(V value) {
         return new IsMapContaining<>(anything(), equalTo(value));
diff --git a/hamcrest/src/main/java/org/hamcrest/collection/IsMapWithSize.java b/hamcrest/src/main/java/org/hamcrest/collection/IsMapWithSize.java
index 99bd3bd7..a780bc5f 100644
--- a/hamcrest/src/main/java/org/hamcrest/collection/IsMapWithSize.java
+++ b/hamcrest/src/main/java/org/hamcrest/collection/IsMapWithSize.java
@@ -29,6 +29,7 @@ protected Integer featureValueOf(Map<? extends K, ? extends V> actual) {
      *
      * @param sizeMatcher
      *     a matcher for the size of an examined {@link java.util.Map}
+v
      */
     public static <K, V> Matcher<Map<? extends K, ? extends V>> aMapWithSize(Matcher<? super Integer> sizeMatcher) {
         return new IsMapWithSize<>(sizeMatcher);
@@ -42,6 +43,7 @@ protected Integer featureValueOf(Map<? extends K, ? extends V> actual) {
      *
      * @param size
      *     the expected size of an examined {@link java.util.Map}
+     * @return The matcher.
      */
     public static <K, V> Matcher<Map<? extends K, ? extends V>> aMapWithSize(int size) {
         return IsMapWithSize.aMapWithSize(equalTo(size));
@@ -52,6 +54,8 @@ protected Integer featureValueOf(Map<? extends K, ? extends V> actual) {
      * zero.
      * For example:
      * <pre>assertThat(myMap, is(anEmptyMap()))</pre>
+     *
+     * @return The matcher.
      */
     public static <K, V> Matcher<Map<? extends K, ? extends V>> anEmptyMap() {
         return IsMapWithSize.aMapWithSize(equalTo(0));
diff --git a/hamcrest/src/main/java/org/hamcrest/core/AllOf.java b/hamcrest/src/main/java/org/hamcrest/core/AllOf.java
index b8c3faad..b21165a4 100644
--- a/hamcrest/src/main/java/org/hamcrest/core/AllOf.java
+++ b/hamcrest/src/main/java/org/hamcrest/core/AllOf.java
@@ -44,6 +44,8 @@ public void describeTo(Description description) {
      * Creates a matcher that matches if the examined object matches <b>ALL</b> of the specified matchers.
      * For example:
      * <pre>assertThat("myValue", allOf(startsWith("my"), containsString("Val")))</pre>
+     *
+     * @return The matcher.
      */
     public static <T> Matcher<T> allOf(Iterable<Matcher<? super T>> matchers) {
         return new AllOf<>(matchers);
@@ -53,6 +55,8 @@ public static <T> Matcher<T> allOf(Iterable<Matcher<? super T>> matchers) {
      * Creates a matcher that matches if the examined object matches <b>ALL</b> of the specified matchers.
      * For example:
      * <pre>assertThat("myValue", allOf(startsWith("my"), containsString("Val")))</pre>
+     *
+     * @return The matcher.
      */
     @SafeVarargs
     public static <T> Matcher<T> allOf(Matcher<? super T>... matchers) {
diff --git a/hamcrest/src/main/java/org/hamcrest/core/AnyOf.java b/hamcrest/src/main/java/org/hamcrest/core/AnyOf.java
index 7a22c22e..c282cd85 100644
--- a/hamcrest/src/main/java/org/hamcrest/core/AnyOf.java
+++ b/hamcrest/src/main/java/org/hamcrest/core/AnyOf.java
@@ -34,6 +34,8 @@ public void describeTo(Description description) {
      * Creates a matcher that matches if the examined object matches <b>ANY</b> of the specified matchers.
      * For example:
      * <pre>assertThat("myValue", anyOf(startsWith("foo"), containsString("Val")))</pre>
+     *
+     * @return The matcher.
      */
     public static <T> AnyOf<T> anyOf(Iterable<Matcher<? super T>> matchers) {
         return new AnyOf<>(matchers);
@@ -43,6 +45,8 @@ public static <T> AnyOf<T> anyOf(Iterable<Matcher<? super T>> matchers) {
      * Creates a matcher that matches if the examined object matches <b>ANY</b> of the specified matchers.
      * For example:
      * <pre>assertThat("myValue", anyOf(startsWith("foo"), containsString("Val")))</pre>
+     *
+     * @return The matcher.
      */
     @SafeVarargs
     public static <T> AnyOf<T> anyOf(Matcher<? super T>... matchers) {
diff --git a/hamcrest/src/main/java/org/hamcrest/core/CombinableMatcher.java b/hamcrest/src/main/java/org/hamcrest/core/CombinableMatcher.java
index e37efce6..97fbb634 100644
--- a/hamcrest/src/main/java/org/hamcrest/core/CombinableMatcher.java
+++ b/hamcrest/src/main/java/org/hamcrest/core/CombinableMatcher.java
@@ -46,6 +46,8 @@ private ArrayList<Matcher<? super T>> templatedListWith(Matcher<? super T> other
    * Creates a matcher that matches when both of the specified matchers match the examined object.
    * For example:
    * <pre>assertThat("fab", both(containsString("a")).and(containsString("b")))</pre>
+   *
+   * @return The matcher.
    */
   public static <LHS> CombinableBothMatcher<LHS> both(Matcher<? super LHS> matcher) {
     return new CombinableBothMatcher<>(matcher);
@@ -65,6 +67,8 @@ public CombinableMatcher<X> and(Matcher<? super X> other) {
    * Creates a matcher that matches when either of the specified matchers match the examined object.
    * For example:
    * <pre>assertThat("fan", either(containsString("a")).or(containsString("b")))</pre>
+   *
+   * @return The matcher.
    */
   public static <LHS> CombinableEitherMatcher<LHS> either(Matcher<? super LHS> matcher) {
     return new CombinableEitherMatcher<>(matcher);
diff --git a/hamcrest/src/main/java/org/hamcrest/core/DescribedAs.java b/hamcrest/src/main/java/org/hamcrest/core/DescribedAs.java
index 0e054290..4b95713b 100644
--- a/hamcrest/src/main/java/org/hamcrest/core/DescribedAs.java
+++ b/hamcrest/src/main/java/org/hamcrest/core/DescribedAs.java
@@ -62,6 +62,7 @@ public void describeMismatch(Object item, Description description) {
      *     the matcher to wrap
      * @param values
      *     optional values to insert into the tokenised description
+     * @return The matcher.
      */
     public static <T> Matcher<T> describedAs(String description, Matcher<T> matcher, Object... values) {
         return new DescribedAs<T>(description, matcher, values);
diff --git a/hamcrest/src/main/java/org/hamcrest/core/Every.java b/hamcrest/src/main/java/org/hamcrest/core/Every.java
index 771c4a9d..cf4fed6d 100644
--- a/hamcrest/src/main/java/org/hamcrest/core/Every.java
+++ b/hamcrest/src/main/java/org/hamcrest/core/Every.java
@@ -37,6 +37,7 @@ public void describeTo(Description description) {
      *
      * @param itemMatcher
      *     the matcher to apply to every item provided by the examined {@link Iterable}
+     * @return The matcher.
      */
     public static <U> Matcher<Iterable<? extends U>> everyItem(final Matcher<U> itemMatcher) {
         return new Every<>(itemMatcher);
diff --git a/hamcrest/src/main/java/org/hamcrest/core/Is.java b/hamcrest/src/main/java/org/hamcrest/core/Is.java
index df0ee322..ffbfd7a7 100644
--- a/hamcrest/src/main/java/org/hamcrest/core/Is.java
+++ b/hamcrest/src/main/java/org/hamcrest/core/Is.java
@@ -42,6 +42,8 @@ public void describeMismatch(Object item, Description mismatchDescription) {
      * <pre>assertThat(cheese, is(equalTo(smelly)))</pre>
      * instead of:
      * <pre>assertThat(cheese, equalTo(smelly))</pre>
+     *
+     * @return The matcher.
      */
     public static <T> Matcher<T> is(Matcher<T> matcher) {
         return new Is<>(matcher);
@@ -53,6 +55,8 @@ public static <T> Matcher<T> is(Matcher<T> matcher) {
      * <pre>assertThat(cheese, is(smelly))</pre>
      * instead of:
      * <pre>assertThat(cheese, is(equalTo(smelly)))</pre>
+     *
+     * @return The matcher.
      */
     public static <T> Matcher<T> is(T value) {
         return is(equalTo(value));
@@ -64,6 +68,8 @@ public static <T> Matcher<T> is(T value) {
      * <pre>assertThat(cheese, isA(Cheddar.class))</pre>
      * instead of:
      * <pre>assertThat(cheese, is(instanceOf(Cheddar.class)))</pre>
+     *
+     * @return The matcher.
      */
     public static <T> Matcher<T> isA(Class<?> type) {
         return is(IsInstanceOf.<T>instanceOf(type));
diff --git a/hamcrest/src/main/java/org/hamcrest/core/IsAnything.java b/hamcrest/src/main/java/org/hamcrest/core/IsAnything.java
index 94943dc0..8a08d3af 100644
--- a/hamcrest/src/main/java/org/hamcrest/core/IsAnything.java
+++ b/hamcrest/src/main/java/org/hamcrest/core/IsAnything.java
@@ -32,6 +32,8 @@ public void describeTo(Description description) {
 
     /**
      * Creates a matcher that always matches, regardless of the examined object.
+     *
+     * @return The matcher.
      */
     public static Matcher<Object> anything() { return new IsAnything<>(); }
 
@@ -41,6 +43,7 @@ public void describeTo(Description description) {
      *
      * @param description
      *     a meaningful {@link String} used when describing itself
+     * @return The matcher.
      */
     public static Matcher<Object> anything(String description) {
         return new IsAnything<>(description);
diff --git a/hamcrest/src/main/java/org/hamcrest/core/IsCollectionContaining.java b/hamcrest/src/main/java/org/hamcrest/core/IsCollectionContaining.java
index 630ea828..0ca8bf65 100644
--- a/hamcrest/src/main/java/org/hamcrest/core/IsCollectionContaining.java
+++ b/hamcrest/src/main/java/org/hamcrest/core/IsCollectionContaining.java
@@ -38,6 +38,7 @@ public void describeTo(Description description) {
      *
      * @param itemMatcher
      *     the matcher to apply to items provided by the examined {@link Iterable}
+     * @return The matcher.
      */
     public static <T> Matcher<Iterable<? super T>> hasItem(Matcher<? super T> itemMatcher) {
         return IsIterableContaining.hasItem(itemMatcher);
@@ -55,6 +56,7 @@ public static <T> Matcher<Iterable<? super T>> hasItem(Matcher<? super T> itemMa
      *
      * @param item
      *     the item to compare against the items provided by the examined {@link Iterable}
+     * @return The matcher.
      */
     public static <T> Matcher<Iterable<? super T>> hasItem(T item) {
         // Doesn't forward to hasItem() method so compiler can sort out generics.
@@ -73,6 +75,7 @@ public static <T> Matcher<Iterable<? super T>> hasItem(T item) {
      *
      * @param itemMatchers
      *     the matchers to apply to items provided by the examined {@link Iterable}
+     * @return The matcher.
      */
     @SafeVarargs
     public static <T> Matcher<Iterable<T>> hasItems(Matcher<? super T>... itemMatchers) {
@@ -91,6 +94,7 @@ public static <T> Matcher<Iterable<T>> hasItems(Matcher<? super T>... itemMatche
      *
      * @param items
      *     the items to compare against the items provided by the examined {@link Iterable}
+     * @return The matcher.
      */
     @SafeVarargs
     public static <T> Matcher<Iterable<T>> hasItems(T... items) {
diff --git a/hamcrest/src/main/java/org/hamcrest/core/IsEqual.java b/hamcrest/src/main/java/org/hamcrest/core/IsEqual.java
index ac2d981b..868d1215 100644
--- a/hamcrest/src/main/java/org/hamcrest/core/IsEqual.java
+++ b/hamcrest/src/main/java/org/hamcrest/core/IsEqual.java
@@ -81,6 +81,8 @@ private static boolean isArray(Object o) {
      * assertThat("foo", equalTo("foo"));
      * assertThat(new String[] {"foo", "bar"}, equalTo(new String[] {"foo", "bar"}));
      * </pre>
+     *
+     * @return The matcher.
      */
     public static <T> Matcher<T> equalTo(T operand) {
         return new IsEqual<>(operand);
@@ -89,6 +91,8 @@ public static <T> Matcher<T> equalTo(T operand) {
     /**
      * Creates an {@link org.hamcrest.core.IsEqual} matcher that does not enforce the values being
      * compared to be of the same static type.
+     *
+     * @return The matcher.
      */
     public static Matcher<Object> equalToObject(Object operand) {
         return new IsEqual<>(operand);
diff --git a/hamcrest/src/main/java/org/hamcrest/core/IsInstanceOf.java b/hamcrest/src/main/java/org/hamcrest/core/IsInstanceOf.java
index 9984655e..1cd202c8 100644
--- a/hamcrest/src/main/java/org/hamcrest/core/IsInstanceOf.java
+++ b/hamcrest/src/main/java/org/hamcrest/core/IsInstanceOf.java
@@ -64,6 +64,8 @@ public void describeTo(Description description) {
      * <p>The created matcher assumes no relationship between specified type and the examined object.</p>
      * For example:
      * <pre>assertThat(new Canoe(), instanceOf(Paddlable.class));</pre>
+     *
+     * @return The matcher.
      */
     @SuppressWarnings("unchecked")
     public static <T> Matcher<T> instanceOf(Class<?> type) {
@@ -80,6 +82,8 @@ public static <T> Matcher<T> instanceOf(Class<?> type) {
      * <code>with(any(Thing.class))</code></p>
      * For example:
      * <pre>assertThat(new Canoe(), instanceOf(Canoe.class));</pre>
+     *
+     * @return The matcher.
      */
     @SuppressWarnings("unchecked")
     public static <T> Matcher<T> any(Class<T> type) {
diff --git a/hamcrest/src/main/java/org/hamcrest/core/IsIterableContaining.java b/hamcrest/src/main/java/org/hamcrest/core/IsIterableContaining.java
index f9cd7434..67016899 100644
--- a/hamcrest/src/main/java/org/hamcrest/core/IsIterableContaining.java
+++ b/hamcrest/src/main/java/org/hamcrest/core/IsIterableContaining.java
@@ -65,6 +65,7 @@ public void describeTo(Description description) {
      *
      * @param itemMatcher
      *     the matcher to apply to items provided by the examined {@link Iterable}
+     * @return The matcher.
      */
     public static <T> Matcher<Iterable<? super T>> hasItem(Matcher<? super T> itemMatcher) {
         return new IsIterableContaining<>(itemMatcher);
@@ -80,6 +81,7 @@ public static <T> Matcher<Iterable<? super T>> hasItem(Matcher<? super T> itemMa
      *
      * @param item
      *     the item to compare against the items provided by the examined {@link Iterable}
+     * @return The matcher.
      */
     public static <T> Matcher<Iterable<? super T>> hasItem(T item) {
         // Doesn't forward to hasItem() method so compiler can sort out generics.
@@ -96,6 +98,7 @@ public static <T> Matcher<Iterable<? super T>> hasItem(T item) {
      *
      * @param itemMatchers
      *     the matchers to apply to items provided by the examined {@link Iterable}
+     * @return The matcher.
      */
     @SafeVarargs
     public static <T> Matcher<Iterable<T>> hasItems(Matcher<? super T>... itemMatchers) {
@@ -119,6 +122,7 @@ public static <T> Matcher<Iterable<T>> hasItems(Matcher<? super T>... itemMatche
      *
      * @param items
      *     the items to compare against the items provided by the examined {@link Iterable}
+     * @return The matcher.
      */
     @SafeVarargs
     public static <T> Matcher<Iterable<T>> hasItems(T... items) {
diff --git a/hamcrest/src/main/java/org/hamcrest/core/IsNot.java b/hamcrest/src/main/java/org/hamcrest/core/IsNot.java
index f81f516a..6db38bef 100644
--- a/hamcrest/src/main/java/org/hamcrest/core/IsNot.java
+++ b/hamcrest/src/main/java/org/hamcrest/core/IsNot.java
@@ -36,6 +36,7 @@ public void describeTo(Description description) {
      *
      * @param matcher
      *     the matcher whose sense should be inverted
+     * @return The matcher.
      */
     public static <T> Matcher<T> not(Matcher<T> matcher) {
         return new IsNot<T>(matcher);
@@ -50,6 +51,7 @@ public static <T> Matcher<T> not(Matcher<T> matcher) {
      *
      * @param value
      *     the value that any examined object should <b>not</b> equal
+     * @return The matcher.
      */
     public static <T> Matcher<T> not(T value) {
         return not(equalTo(value));
diff --git a/hamcrest/src/main/java/org/hamcrest/core/IsNull.java b/hamcrest/src/main/java/org/hamcrest/core/IsNull.java
index ded83efe..328daffa 100644
--- a/hamcrest/src/main/java/org/hamcrest/core/IsNull.java
+++ b/hamcrest/src/main/java/org/hamcrest/core/IsNull.java
@@ -24,6 +24,8 @@ public void describeTo(Description description) {
      * Creates a matcher that matches if examined object is <code>null</code>.
      * For example:
      * <pre>assertThat(cheese, is(nullValue())</pre>
+     *
+     * @return The matcher.
      */
     public static Matcher<Object> nullValue() {
         return new IsNull<Object>();
@@ -35,6 +37,8 @@ public static Matcher<Object> nullValue() {
      * <pre>assertThat(cheese, is(notNullValue()))</pre>
      * instead of:
      * <pre>assertThat(cheese, is(not(nullValue())))</pre>
+     *
+     * @return The matcher.
      */
     public static Matcher<Object> notNullValue() {
         return not(nullValue());
@@ -48,6 +52,7 @@ public static Matcher<Object> notNullValue() {
      *
      * @param type
      *     dummy parameter used to infer the generic type of the returned matcher
+     * @return The matcher.
      */
     public static <T> Matcher<T> nullValue(Class<T> type) {
         return new IsNull<T>();
@@ -63,6 +68,7 @@ public static <T> Matcher<T> nullValue(Class<T> type) {
      *
      * @param type
      *     dummy parameter used to infer the generic type of the returned matcher
+     * @return The matcher.
      */
     public static <T> Matcher<T> notNullValue(Class<T> type) {
         return not(nullValue(type));
diff --git a/hamcrest/src/main/java/org/hamcrest/core/IsSame.java b/hamcrest/src/main/java/org/hamcrest/core/IsSame.java
index cbc3971b..da39f91a 100644
--- a/hamcrest/src/main/java/org/hamcrest/core/IsSame.java
+++ b/hamcrest/src/main/java/org/hamcrest/core/IsSame.java
@@ -33,6 +33,7 @@ public void describeTo(Description description) {
      *
      * @param target
      *     the target instance against which others should be assessed
+     * @return The matcher.
      */
     public static <T> Matcher<T> sameInstance(T target) {
         return new IsSame<T>(target);
@@ -44,6 +45,7 @@ public static <T> Matcher<T> sameInstance(T target) {
      *
      * @param target
      *     the target instance against which others should be assessed
+     * @return The matcher.
      */
     public static <T> Matcher<T> theInstance(T target) {
         return new IsSame<T>(target);
diff --git a/hamcrest/src/main/java/org/hamcrest/core/StringContains.java b/hamcrest/src/main/java/org/hamcrest/core/StringContains.java
index e32b2e0a..dab7d4d9 100644
--- a/hamcrest/src/main/java/org/hamcrest/core/StringContains.java
+++ b/hamcrest/src/main/java/org/hamcrest/core/StringContains.java
@@ -25,6 +25,7 @@ protected boolean evalSubstringOf(String s) {
      *
      * @param substring
      *     the substring that the returned matcher will expect to find within any examined string
+     * @return The matcher.
      */
     public static Matcher<String> containsString(String substring) {
         return new StringContains(false, substring);
@@ -38,6 +39,7 @@ public static Matcher<String> containsString(String substring) {
      *
      * @param substring
      *     the substring that the returned matcher will expect to find within any examined string
+     * @return The matcher.
      */
     public static Matcher<String> containsStringIgnoringCase(String substring) {
         return new StringContains(true, substring);
diff --git a/hamcrest/src/main/java/org/hamcrest/core/StringEndsWith.java b/hamcrest/src/main/java/org/hamcrest/core/StringEndsWith.java
index e815d0fb..96bbf29b 100644
--- a/hamcrest/src/main/java/org/hamcrest/core/StringEndsWith.java
+++ b/hamcrest/src/main/java/org/hamcrest/core/StringEndsWith.java
@@ -23,6 +23,7 @@ protected boolean evalSubstringOf(String s) {
      *
      * @param suffix
      *      the substring that the returned matcher will expect at the end of any examined string
+     * @return The matcher.
      */
     public static Matcher<String> endsWith(String suffix) {
         return new StringEndsWith(false, suffix);
@@ -36,6 +37,7 @@ public static Matcher<String> endsWith(String suffix) {
      *
      * @param suffix
      *      the substring that the returned matcher will expect at the end of any examined string
+     * @return The matcher.
      */
     public static Matcher<String> endsWithIgnoringCase(String suffix) {
         return new StringEndsWith(true, suffix);
diff --git a/hamcrest/src/main/java/org/hamcrest/core/StringStartsWith.java b/hamcrest/src/main/java/org/hamcrest/core/StringStartsWith.java
index 354d4426..7043fbff 100644
--- a/hamcrest/src/main/java/org/hamcrest/core/StringStartsWith.java
+++ b/hamcrest/src/main/java/org/hamcrest/core/StringStartsWith.java
@@ -23,6 +23,7 @@ public class StringStartsWith extends SubstringMatcher {
      *
      * @param prefix
      *      the substring that the returned matcher will expect at the start of any examined string
+     * @return The matcher.
      */
     public static Matcher<String> startsWith(String prefix) { return new StringStartsWith(false, prefix); }
 
@@ -36,6 +37,7 @@ public class StringStartsWith extends SubstringMatcher {
      *
      * @param prefix
      *      the substring that the returned matcher will expect at the start of any examined string
+     * @return The matcher.
      */
     public static Matcher<String> startsWithIgnoringCase(String prefix) { return new StringStartsWith(true, prefix); }
 
diff --git a/hamcrest/src/main/java/org/hamcrest/number/BigDecimalCloseTo.java b/hamcrest/src/main/java/org/hamcrest/number/BigDecimalCloseTo.java
index d9cb0264..4862f30c 100644
--- a/hamcrest/src/main/java/org/hamcrest/number/BigDecimalCloseTo.java
+++ b/hamcrest/src/main/java/org/hamcrest/number/BigDecimalCloseTo.java
@@ -54,6 +54,7 @@ private BigDecimal actualDelta(BigDecimal item) {
    *     the expected value of matching BigDecimals
    * @param error
    *     the delta (+/-) within which matches will be allowed
+   * @return The matcher.
    */
   public static Matcher<BigDecimal> closeTo(BigDecimal operand, BigDecimal error) {
       return new BigDecimalCloseTo(operand, error);
diff --git a/hamcrest/src/main/java/org/hamcrest/number/IsCloseTo.java b/hamcrest/src/main/java/org/hamcrest/number/IsCloseTo.java
index 6525b8f6..cc6b74bb 100644
--- a/hamcrest/src/main/java/org/hamcrest/number/IsCloseTo.java
+++ b/hamcrest/src/main/java/org/hamcrest/number/IsCloseTo.java
@@ -56,6 +56,7 @@ private double actualDelta(Double item) {
      *     the expected value of matching doubles
      * @param error
      *     the delta (+/-) within which matches will be allowed
+     * @return The matcher.
      */
     public static Matcher<Double> closeTo(double operand, double error) {
         return new IsCloseTo(operand, error);
diff --git a/hamcrest/src/main/java/org/hamcrest/number/IsNaN.java b/hamcrest/src/main/java/org/hamcrest/number/IsNaN.java
index 415a9a2b..31fcdf82 100644
--- a/hamcrest/src/main/java/org/hamcrest/number/IsNaN.java
+++ b/hamcrest/src/main/java/org/hamcrest/number/IsNaN.java
@@ -31,6 +31,8 @@ public void describeTo(Description description) {
      * Creates a matcher of {@link Double}s that matches when an examined double is not a number.
      * For example:
      * <pre>assertThat(Double.NaN, is(notANumber()))</pre>
+     *
+     * @return The matcher.
      */
     public static Matcher<Double> notANumber() {
         return new IsNaN();
diff --git a/hamcrest/src/main/java/org/hamcrest/number/OrderingComparison.java b/hamcrest/src/main/java/org/hamcrest/number/OrderingComparison.java
index 8a77713d..f5f98150 100644
--- a/hamcrest/src/main/java/org/hamcrest/number/OrderingComparison.java
+++ b/hamcrest/src/main/java/org/hamcrest/number/OrderingComparison.java
@@ -16,6 +16,7 @@ private OrderingComparison() {
      * <pre>assertThat(1, comparesEqualTo(1))</pre>
      *
      * @param value the value which, when passed to the compareTo method of the examined object, should return zero
+     * @return The matcher.
      */
     public static <T extends Comparable<T>> Matcher<T> comparesEqualTo(T value) {
         return ComparatorMatcherBuilder.<T>usingNaturalOrdering().comparesEqualTo(value);
@@ -30,6 +31,7 @@ public static <T extends Comparable<T>> Matcher<T> comparesEqualTo(T value) {
      *
      * @param value the value which, when passed to the compareTo method of the examined object, should return greater
      *              than zero
+     * @return The matcher.
      */
     public static <T extends Comparable<T>> Matcher<T> greaterThan(T value) {
         return ComparatorMatcherBuilder.<T>usingNaturalOrdering().greaterThan(value);
@@ -44,6 +46,7 @@ public static <T extends Comparable<T>> Matcher<T> greaterThan(T value) {
      *
      * @param value the value which, when passed to the compareTo method of the examined object, should return greater
      *              than or equal to zero
+     * @return The matcher.
      */
     public static <T extends Comparable<T>> Matcher<T> greaterThanOrEqualTo(T value) {
         return ComparatorMatcherBuilder.<T>usingNaturalOrdering().greaterThanOrEqualTo(value);
@@ -58,6 +61,7 @@ public static <T extends Comparable<T>> Matcher<T> greaterThanOrEqualTo(T value)
      *
      * @param value the value which, when passed to the compareTo method of the examined object, should return less
      *              than zero
+     * @return The matcher.
      */
     public static <T extends Comparable<T>> Matcher<T> lessThan(T value) {
         return ComparatorMatcherBuilder.<T>usingNaturalOrdering().lessThan(value);
@@ -72,6 +76,7 @@ public static <T extends Comparable<T>> Matcher<T> lessThan(T value) {
      *
      * @param value the value which, when passed to the compareTo method of the examined object, should return less
      *              than or equal to zero
+     * @return The matcher.
      */
     public static <T extends Comparable<T>> Matcher<T> lessThanOrEqualTo(T value) {
         return ComparatorMatcherBuilder.<T>usingNaturalOrdering().lessThanOrEqualTo(value);
diff --git a/hamcrest/src/main/java/org/hamcrest/object/HasToString.java b/hamcrest/src/main/java/org/hamcrest/object/HasToString.java
index 0c0aa49e..e807674f 100644
--- a/hamcrest/src/main/java/org/hamcrest/object/HasToString.java
+++ b/hamcrest/src/main/java/org/hamcrest/object/HasToString.java
@@ -23,6 +23,7 @@ protected String featureValueOf(T actual) {
      *
      * @param toStringMatcher
      *     the matcher used to verify the toString result
+     * @return The matcher.
      */
     public static <T> Matcher<T> hasToString(Matcher<? super String> toStringMatcher) {
         return new HasToString<T>(toStringMatcher);
@@ -36,6 +37,7 @@ public static <T> Matcher<T> hasToString(Matcher<? super String> toStringMatcher
      *
      * @param expectedToString
      *     the expected toString result
+     * @return The matcher.
      */
     public static <T> Matcher<T> hasToString(String expectedToString) {
         return new HasToString<T>(equalTo(expectedToString));
diff --git a/hamcrest/src/main/java/org/hamcrest/object/IsCompatibleType.java b/hamcrest/src/main/java/org/hamcrest/object/IsCompatibleType.java
index acb8ddd1..388f1187 100644
--- a/hamcrest/src/main/java/org/hamcrest/object/IsCompatibleType.java
+++ b/hamcrest/src/main/java/org/hamcrest/object/IsCompatibleType.java
@@ -34,6 +34,7 @@ public void describeTo(Description description) {
      *
      * @param baseType
      *     the base class to examine classes against
+     * @return The matcher.
      */
     public static <T> Matcher<Class<?>> typeCompatibleWith(Class<T> baseType) {
         return new IsCompatibleType<T>(baseType);
diff --git a/hamcrest/src/main/java/org/hamcrest/object/IsEventFrom.java b/hamcrest/src/main/java/org/hamcrest/object/IsEventFrom.java
index 50ed998c..784acf39 100644
--- a/hamcrest/src/main/java/org/hamcrest/object/IsEventFrom.java
+++ b/hamcrest/src/main/java/org/hamcrest/object/IsEventFrom.java
@@ -56,6 +56,7 @@ public void describeTo(Description description) {
      *     the class of the event to match on
      * @param source
      *     the source of the event
+     * @return The matcher.
      */
     public static Matcher<EventObject> eventFrom(Class<? extends EventObject> eventClass, Object source) {
         return new IsEventFrom(eventClass, source);
@@ -69,6 +70,7 @@ public static Matcher<EventObject> eventFrom(Class<? extends EventObject> eventC
      *
      * @param source
      *     the source of the event
+     * @return The matcher.
      */
     public static Matcher<EventObject> eventFrom(Object source) {
         return eventFrom(EventObject.class, source);
diff --git a/hamcrest/src/main/java/org/hamcrest/text/CharSequenceLength.java b/hamcrest/src/main/java/org/hamcrest/text/CharSequenceLength.java
index 4324eade..111a1e7d 100644
--- a/hamcrest/src/main/java/org/hamcrest/text/CharSequenceLength.java
+++ b/hamcrest/src/main/java/org/hamcrest/text/CharSequenceLength.java
@@ -33,6 +33,7 @@ protected Integer featureValueOf(CharSequence actual) {
      * </pre>
      *
      * @param length the expected length of the string
+     * @return The matcher.
      */
     public static Matcher<CharSequence> hasLength(int length) {
         return new CharSequenceLength(equalTo(length));
@@ -47,6 +48,7 @@ public static Matcher<CharSequence> hasLength(int length) {
       * </pre>
       *
       * @param lengthMatcher the expected length of the string
+      * @return The matcher.
       */
      @SuppressWarnings("WeakerAccess")
      public static Matcher<CharSequence> hasLength(Matcher<? super Integer> lengthMatcher) {
diff --git a/hamcrest/src/main/java/org/hamcrest/text/IsBlankString.java b/hamcrest/src/main/java/org/hamcrest/text/IsBlankString.java
index c05613a8..19a9ec3c 100644
--- a/hamcrest/src/main/java/org/hamcrest/text/IsBlankString.java
+++ b/hamcrest/src/main/java/org/hamcrest/text/IsBlankString.java
@@ -37,6 +37,8 @@ public void describeTo(Description description) {
      * zero or more whitespace characters and nothing else.
      * For example:
      * <pre>assertThat("  ", is(blankString()))</pre>
+     *
+     * @return The matcher.
      */
     public static Matcher<String> blankString() {
         return BLANK_INSTANCE;
@@ -47,6 +49,8 @@ public static Matcher<String> blankString() {
      * contains zero or more whitespace characters and nothing else.
      * For example:
      * <pre>assertThat(((String)null), is(blankOrNullString()))</pre>
+     *
+     * @return The matcher.
      */
     public static Matcher<String> blankOrNullString() {
         return NULL_OR_BLANK_INSTANCE;
diff --git a/hamcrest/src/main/java/org/hamcrest/text/IsEmptyString.java b/hamcrest/src/main/java/org/hamcrest/text/IsEmptyString.java
index dd78449a..8fdf0bb5 100644
--- a/hamcrest/src/main/java/org/hamcrest/text/IsEmptyString.java
+++ b/hamcrest/src/main/java/org/hamcrest/text/IsEmptyString.java
@@ -34,6 +34,7 @@ public void describeTo(Description description) {
      * <pre>assertThat("", isEmptyString())</pre>
      *
      * @deprecated use is(emptyString()) instead
+     * @return The matcher.
      */
     @Deprecated
     public static Matcher<String> isEmptyString() {
@@ -44,6 +45,8 @@ public static Matcher<String> isEmptyString() {
      * Creates a matcher of {@link String} that matches when the examined string has zero length.
      * For example:
      * <pre>assertThat("", is(emptyString()))</pre>
+     *
+     * @return The matcher.
      */
     public static Matcher<String> emptyString() {
         return INSTANCE;
@@ -56,6 +59,7 @@ public static Matcher<String> emptyString() {
      * <pre>assertThat(((String)null), isEmptyOrNullString())</pre>
      *
      * @deprecated use is(emptyOrNullString()) instead
+     * @return The matcher.
      */
     @Deprecated
     public static Matcher<String> isEmptyOrNullString() {
@@ -67,6 +71,8 @@ public static Matcher<String> isEmptyOrNullString() {
      * has zero length.
      * For example:
      * <pre>assertThat(((String)null), is(emptyOrNullString()))</pre>
+     *
+     * @return The matcher.
      */
     public static Matcher<String> emptyOrNullString() {
         return NULL_OR_EMPTY_INSTANCE;
diff --git a/hamcrest/src/main/java/org/hamcrest/text/IsEqualCompressingWhiteSpace.java b/hamcrest/src/main/java/org/hamcrest/text/IsEqualCompressingWhiteSpace.java
index 15d7a877..1bf266af 100644
--- a/hamcrest/src/main/java/org/hamcrest/text/IsEqualCompressingWhiteSpace.java
+++ b/hamcrest/src/main/java/org/hamcrest/text/IsEqualCompressingWhiteSpace.java
@@ -46,6 +46,7 @@ public String stripSpaces(String toBeStripped) {
      * @deprecated {@link #equalToCompressingWhiteSpace(String)}
      * @param expectedString
      *     the expected value of matched strings
+     * @return The matcher.
      */
     public static Matcher<String> equalToIgnoringWhiteSpace(String expectedString) {
         return new IsEqualCompressingWhiteSpace(expectedString);
@@ -64,6 +65,7 @@ public static Matcher<String> equalToIgnoringWhiteSpace(String expectedString) {
      *
      * @param expectedString
      *     the expected value of matched strings
+     * @return The matcher.
      */
     public static Matcher<String> equalToCompressingWhiteSpace(String expectedString) {
         return new IsEqualCompressingWhiteSpace(expectedString);
diff --git a/hamcrest/src/main/java/org/hamcrest/text/IsEqualIgnoringCase.java b/hamcrest/src/main/java/org/hamcrest/text/IsEqualIgnoringCase.java
index d44fb67b..fccaa0cc 100644
--- a/hamcrest/src/main/java/org/hamcrest/text/IsEqualIgnoringCase.java
+++ b/hamcrest/src/main/java/org/hamcrest/text/IsEqualIgnoringCase.java
@@ -46,6 +46,7 @@ public void describeTo(Description description) {
      *
      * @param expectedString
      *     the expected value of matched strings
+     * @return The matcher.
      */
     public static Matcher<String> equalToIgnoringCase(String expectedString) {
         return new IsEqualIgnoringCase(expectedString);
diff --git a/hamcrest/src/main/java/org/hamcrest/text/MatchesPattern.java b/hamcrest/src/main/java/org/hamcrest/text/MatchesPattern.java
index e0eda0a8..53462953 100644
--- a/hamcrest/src/main/java/org/hamcrest/text/MatchesPattern.java
+++ b/hamcrest/src/main/java/org/hamcrest/text/MatchesPattern.java
@@ -26,6 +26,8 @@ public void describeTo(Description description) {
     /**
      * Creates a matcher of {@link java.lang.String} that matches when the examined string
      * exactly matches the given {@link java.util.regex.Pattern}.
+     *
+     * @return The matcher.
      */
     public static Matcher<String> matchesPattern(Pattern pattern) {
         return new MatchesPattern(pattern);
@@ -34,6 +36,8 @@ public static Matcher<String> matchesPattern(Pattern pattern) {
     /**
      * Creates a matcher of {@link java.lang.String} that matches when the examined string
      * exactly matches the given regular expression, treated as a {@link java.util.regex.Pattern}.
+     *
+     * @return The matcher.
      */
     public static Matcher<String> matchesPattern(String regex) {
         return new MatchesPattern(Pattern.compile(regex));
diff --git a/hamcrest/src/main/java/org/hamcrest/text/StringContainsInOrder.java b/hamcrest/src/main/java/org/hamcrest/text/StringContainsInOrder.java
index d324baba..e95b8ee9 100644
--- a/hamcrest/src/main/java/org/hamcrest/text/StringContainsInOrder.java
+++ b/hamcrest/src/main/java/org/hamcrest/text/StringContainsInOrder.java
@@ -49,6 +49,7 @@ public void describeTo(Description description) {
      *
      * @param substrings
      *     the substrings that must be contained within matching strings
+     * @return The matcher.
      */
     public static Matcher<String> stringContainsInOrder(Iterable<String> substrings) {
         return new StringContainsInOrder(substrings);
@@ -63,6 +64,7 @@ public static Matcher<String> stringContainsInOrder(Iterable<String> substrings)
      *
      * @param substrings
      *     the substrings that must be contained within matching strings
+     * @return The matcher.
      */
     public static Matcher<String> stringContainsInOrder(String... substrings) {
         return new StringContainsInOrder(Arrays.asList(substrings));