JavaDoc only @return org.hamcrest

hamcrest · Feb 13, 2022 · fce23bf · fce23bf
1 parent f627f9b
commit fce23bf
Show file tree

Hide file tree

Showing 6 changed files with 238 additions and 0 deletions.
diff --git a/hamcrest/src/main/java/org/hamcrest/CoreMatchers.java b/hamcrest/src/main/java/org/hamcrest/CoreMatchers.java
@@ -9,6 +9,8 @@ public class CoreMatchers {
    * 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> org.hamcrest.Matcher<T> allOf(java.lang.Iterable<org.hamcrest.Matcher<? super T>> matchers) {
     return org.hamcrest.core.AllOf.allOf(matchers);
@@ -18,6 +20,8 @@ public static <T> org.hamcrest.Matcher<T> allOf(java.lang.Iterable<org.hamcrest.
    * 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> org.hamcrest.Matcher<T> allOf(org.hamcrest.Matcher<? super T>... matchers) {
@@ -29,6 +33,8 @@ public static <T> org.hamcrest.Matcher<T> allOf(org.hamcrest.Matcher<? super T>.
    * 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> org.hamcrest.core.AnyOf<T> anyOf(java.lang.Iterable<org.hamcrest.Matcher<? super T>> matchers) {
     return org.hamcrest.core.AnyOf.anyOf(matchers);
@@ -38,6 +44,8 @@ public static <T> org.hamcrest.core.AnyOf<T> anyOf(java.lang.Iterable<org.hamcre
    * 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> org.hamcrest.core.AnyOf<T> anyOf(org.hamcrest.Matcher<? super T>... matchers) {
@@ -48,6 +56,8 @@ public static <T> org.hamcrest.core.AnyOf<T> anyOf(org.hamcrest.Matcher<? super
    * 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> org.hamcrest.core.CombinableMatcher.CombinableBothMatcher<LHS> both(org.hamcrest.Matcher<? super LHS> matcher) {
     return org.hamcrest.core.CombinableMatcher.both(matcher);
@@ -57,6 +67,8 @@ public static <LHS> org.hamcrest.core.CombinableMatcher.CombinableBothMatcher<LH
    * 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> org.hamcrest.core.CombinableMatcher.CombinableEitherMatcher<LHS> either(org.hamcrest.Matcher<? super LHS> matcher) {
     return org.hamcrest.core.CombinableMatcher.either(matcher);
@@ -74,6 +86,8 @@ public static <LHS> org.hamcrest.core.CombinableMatcher.CombinableEitherMatcher<
    *     the matcher to wrap
    * @param values
    *     optional values to insert into the tokenised description
+   *
+   * @return The matcher.
    */
   public static <T> org.hamcrest.Matcher<T> describedAs(java.lang.String description, org.hamcrest.Matcher<T> matcher, java.lang.Object... values) {
     return org.hamcrest.core.DescribedAs.describedAs(description, matcher, values);
@@ -88,6 +102,8 @@ public static <T> org.hamcrest.Matcher<T> describedAs(java.lang.String descripti
    *
    * @param itemMatcher
    *     the matcher to apply to every item provided by the examined {@link Iterable}
+   *
+   * @return The matcher.
    */
   public static <U> org.hamcrest.Matcher<java.lang.Iterable<? extends U>> everyItem(org.hamcrest.Matcher<U> itemMatcher) {
     return org.hamcrest.core.Every.everyItem(itemMatcher);
@@ -100,6 +116,8 @@ public static <U> org.hamcrest.Matcher<java.lang.Iterable<? extends U>> everyIte
    * <pre>assertThat(cheese, is(equalTo(smelly)))</pre>
    * instead of:
    * <pre>assertThat(cheese, equalTo(smelly))</pre>
+   *
+   * @return The matcher.
    */
   public static <T> org.hamcrest.Matcher<T> is(org.hamcrest.Matcher<T> matcher) {
     return org.hamcrest.core.Is.is(matcher);
@@ -111,6 +129,8 @@ public static <T> org.hamcrest.Matcher<T> is(org.hamcrest.Matcher<T> matcher) {
    * <pre>assertThat(cheese, is(smelly))</pre>
    * instead of:
    * <pre>assertThat(cheese, is(equalTo(smelly)))</pre>
+   *
+   * @return The matcher.
    */
   public static <T> org.hamcrest.Matcher<T> is(T value) {
     return org.hamcrest.core.Is.is(value);
@@ -122,13 +142,17 @@ public static <T> org.hamcrest.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> org.hamcrest.Matcher<T> isA(java.lang.Class<T> type) {
     return org.hamcrest.core.Is.isA(type);
   }
 
   /**
    * Creates a matcher that always matches, regardless of the examined object.
+   *
+   * @return The matcher.
    */
   public static org.hamcrest.Matcher<java.lang.Object> anything() {
     return org.hamcrest.core.IsAnything.anything();
@@ -140,6 +164,8 @@ public static org.hamcrest.Matcher<java.lang.Object> anything() {
    * 
    * @param description
    *     a meaningful {@link String} used when describing itself
+   *
+   * @return The matcher.
    */
   public static org.hamcrest.Matcher<java.lang.Object> anything(java.lang.String description) {
     return org.hamcrest.core.IsAnything.anything(description);
@@ -155,6 +181,8 @@ public static org.hamcrest.Matcher<java.lang.Object> anything(java.lang.String d
    * 
    * @param itemMatcher
    *     the matcher to apply to items provided by the examined {@link Iterable}
+   *
+   * @return The matcher.
    */
   public static <T> org.hamcrest.Matcher<java.lang.Iterable<? super T>> hasItem(org.hamcrest.Matcher<? super T> itemMatcher) {
     return IsIterableContaining.hasItem(itemMatcher);
@@ -170,6 +198,8 @@ public static <T> org.hamcrest.Matcher<java.lang.Iterable<? super T>> hasItem(or
    * 
    * @param item
    *     the item to compare against the items provided by the examined {@link Iterable}
+   *
+   * @return The matcher.
    */
   public static <T> org.hamcrest.Matcher<java.lang.Iterable<? super T>> hasItem(T item) {
     return IsIterableContaining.hasItem(item);
@@ -185,6 +215,8 @@ public static <T> org.hamcrest.Matcher<java.lang.Iterable<? super T>> hasItem(T
    * 
    * @param itemMatchers
    *     the matchers to apply to items provided by the examined {@link Iterable}
+   *
+   * @return The matcher.
    */
   @SafeVarargs
   public static <T> org.hamcrest.Matcher<java.lang.Iterable<T>> hasItems(org.hamcrest.Matcher<? super T>... itemMatchers) {
@@ -201,6 +233,8 @@ public static <T> org.hamcrest.Matcher<java.lang.Iterable<T>> hasItems(org.hamcr
    * 
    * @param items
    *     the items to compare against the items provided by the examined {@link Iterable}
+   *
+   * @return The matcher.
    */
   @SafeVarargs
   public static <T> org.hamcrest.Matcher<java.lang.Iterable<T>> hasItems(T... items) {
@@ -227,6 +261,8 @@ public static <T> org.hamcrest.Matcher<java.lang.Iterable<T>> hasItems(T... item
    * assertThat("foo", equalTo("foo"));
    * assertThat(new String[] {"foo", "bar"}, equalTo(new String[] {"foo", "bar"}));
    * </pre>
+   *
+   * @return The matcher.
    */
   public static <T> org.hamcrest.Matcher<T> equalTo(T operand) {
     return org.hamcrest.core.IsEqual.equalTo(operand);
@@ -235,6 +271,8 @@ public static <T> org.hamcrest.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 org.hamcrest.Matcher<java.lang.Object> equalToObject(java.lang.Object operand) {
     return org.hamcrest.core.IsEqual.equalToObject(operand);
@@ -250,6 +288,8 @@ public static org.hamcrest.Matcher<java.lang.Object> equalToObject(java.lang.Obj
    * <code>with(any(Thing.class))</code></p>
    * For example:
    * <pre>assertThat(new Canoe(), any(Canoe.class));</pre>
+   *
+   * @return The matcher.
    */
   public static <T> org.hamcrest.Matcher<T> any(java.lang.Class<T> type) {
     return org.hamcrest.core.IsInstanceOf.any(type);
@@ -263,6 +303,8 @@ public static <T> org.hamcrest.Matcher<T> any(java.lang.Class<T> type) {
    * <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.
    */
   public static <T> org.hamcrest.Matcher<T> instanceOf(java.lang.Class<?> type) {
     return org.hamcrest.core.IsInstanceOf.instanceOf(type);
@@ -276,6 +318,7 @@ public static <T> org.hamcrest.Matcher<T> instanceOf(java.lang.Class<?> type) {
    * 
    * @param matcher
    *     the matcher whose sense should be inverted
+   * @return The matcher.
    */
   public static <T> org.hamcrest.Matcher<T> not(org.hamcrest.Matcher<T> matcher) {
     return org.hamcrest.core.IsNot.not(matcher);
@@ -290,6 +333,7 @@ public static <T> org.hamcrest.Matcher<T> not(org.hamcrest.Matcher<T> matcher) {
    * 
    * @param value
    *     the value that any examined object should <b>not</b> equal
+   * @return The matcher.
    */
   public static <T> org.hamcrest.Matcher<T> not(T value) {
     return org.hamcrest.core.IsNot.not(value);
@@ -301,6 +345,8 @@ public static <T> org.hamcrest.Matcher<T> not(T value) {
    * <pre>assertThat(cheese, is(notNullValue()))</pre>
    * instead of:
    * <pre>assertThat(cheese, is(not(nullValue())))</pre>
+   *
+   * @return The matcher.
    */
   public static org.hamcrest.Matcher<java.lang.Object> notNullValue() {
     return org.hamcrest.core.IsNull.notNullValue();
@@ -316,6 +362,7 @@ public static org.hamcrest.Matcher<java.lang.Object> notNullValue() {
    * 
    * @param type
    *     dummy parameter used to infer the generic type of the returned matcher
+   * @return The matcher.
    */
   public static <T> org.hamcrest.Matcher<T> notNullValue(java.lang.Class<T> type) {
     return org.hamcrest.core.IsNull.notNullValue(type);
@@ -325,6 +372,8 @@ public static <T> org.hamcrest.Matcher<T> notNullValue(java.lang.Class<T> type)
    * 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 org.hamcrest.Matcher<java.lang.Object> nullValue() {
     return org.hamcrest.core.IsNull.nullValue();
@@ -338,6 +387,7 @@ public static org.hamcrest.Matcher<java.lang.Object> nullValue() {
    * 
    * @param type
    *     dummy parameter used to infer the generic type of the returned matcher
+   * @return The matcher.
    */
   public static <T> org.hamcrest.Matcher<T> nullValue(java.lang.Class<T> type) {
     return org.hamcrest.core.IsNull.nullValue(type);
@@ -349,6 +399,7 @@ public static <T> org.hamcrest.Matcher<T> nullValue(java.lang.Class<T> type) {
    * 
    * @param target
    *     the target instance against which others should be assessed
+   * @return The matcher.
    */
   public static <T> org.hamcrest.Matcher<T> sameInstance(T target) {
     return org.hamcrest.core.IsSame.sameInstance(target);
@@ -360,6 +411,7 @@ public static <T> org.hamcrest.Matcher<T> sameInstance(T target) {
    * 
    * @param target
    *     the target instance against which others should be assessed
+   * @return The matcher.
    */
   public static <T> org.hamcrest.Matcher<T> theInstance(T target) {
     return org.hamcrest.core.IsSame.theInstance(target);
@@ -373,6 +425,7 @@ public static <T> org.hamcrest.Matcher<T> theInstance(T target) {
    * 
    * @param substring
    *     the substring that the returned matcher will expect to find within any examined string
+   * @return The matcher.
    */
   public static org.hamcrest.Matcher<java.lang.String> containsString(java.lang.String substring) {
     return org.hamcrest.core.StringContains.containsString(substring);
@@ -386,6 +439,7 @@ public static org.hamcrest.Matcher<java.lang.String> containsString(java.lang.St
    * 
    * @param substring
    *     the substring that the returned matcher will expect to find within any examined string
+   * @return The matcher.
    */
   public static org.hamcrest.Matcher<java.lang.String> containsStringIgnoringCase(java.lang.String substring) {
     return org.hamcrest.core.StringContains.containsStringIgnoringCase(substring);
@@ -401,6 +455,7 @@ public static org.hamcrest.Matcher<java.lang.String> containsStringIgnoringCase(
    * 
    * @param prefix
    *      the substring that the returned matcher will expect at the start of any examined string
+   * @return The matcher.
    */
   public static org.hamcrest.Matcher<java.lang.String> startsWith(java.lang.String prefix) {
     return org.hamcrest.core.StringStartsWith.startsWith(prefix);
@@ -416,6 +471,7 @@ public static org.hamcrest.Matcher<java.lang.String> startsWith(java.lang.String
    * 
    * @param prefix
    *      the substring that the returned matcher will expect at the start of any examined string
+   * @return The matcher.
    */
   public static org.hamcrest.Matcher<java.lang.String> startsWithIgnoringCase(java.lang.String prefix) {
     return org.hamcrest.core.StringStartsWith.startsWithIgnoringCase(prefix);
@@ -429,6 +485,7 @@ public static org.hamcrest.Matcher<java.lang.String> startsWithIgnoringCase(java
    * 
    * @param suffix
    *      the substring that the returned matcher will expect at the end of any examined string
+   * @return The matcher.
    */
   public static org.hamcrest.Matcher<java.lang.String> endsWith(java.lang.String suffix) {
     return org.hamcrest.core.StringEndsWith.endsWith(suffix);
@@ -442,6 +499,7 @@ public static org.hamcrest.Matcher<java.lang.String> endsWith(java.lang.String s
    * 
    * @param suffix
    *      the substring that the returned matcher will expect at the end of any examined string
+   * @return The matcher.
    */
   public static org.hamcrest.Matcher<java.lang.String> endsWithIgnoringCase(java.lang.String suffix) {
     return org.hamcrest.core.StringEndsWith.endsWithIgnoringCase(suffix);

diff --git a/hamcrest/src/main/java/org/hamcrest/Description.java b/hamcrest/src/main/java/org/hamcrest/Description.java
@@ -14,34 +14,46 @@ public interface Description {
 
     /**
      * Appends some plain text to the description.
+     *
+     * @return the update description when displaying the matcher error.
      */
     Description appendText(String text);
 
     /**
      * Appends the description of a {@link SelfDescribing} value to this description.
+     *
+     * @return the update description when displaying the matcher error.
      */
     Description appendDescriptionOf(SelfDescribing value);
 
     /**
      * Appends an arbitrary value to the description.
+     *
+     * @return the update description when displaying the matcher error.
      */
     Description appendValue(Object value);
 
     /**
      * Appends a list of values to the description.
+     *
+     * @return the update description when displaying the matcher error.
      */
     <T> Description appendValueList(String start, String separator, String end,
                                     T... values);
 
     /**
      * Appends a list of values to the description.
+     *
+     * @return the update description when displaying the matcher error.
      */
     <T> Description appendValueList(String start, String separator, String end,
                                     Iterable<T> values);
 
     /**
      * Appends a list of {@link org.hamcrest.SelfDescribing} objects
      * to the description.
+     *
+     * @return the update description when displaying the matcher error.
      */
     Description appendList(String start, String separator, String end,
                            Iterable<? extends SelfDescribing> values);