Javadoc improvements

Author: joel-costigliola

src/main/java/org/assertj/core/api/AbstractIterableAssert.java

@@ -1244,14 +1244,6 @@ public AbstractListAssert<?, List<? extends Tuple>, Tuple, ObjectAssert<Tuple>>
    * fellowshipOfTheRing.add(new TolkienCharacter(&quot;Aragorn&quot;, 87, MAN);
    * fellowshipOfTheRing.add(new TolkienCharacter(&quot;Boromir&quot;, 37, MAN));
    *
-   * // this extracts the race
-   * Function&lt;TolkienCharacter, Race&gt; race = new Function&lt;TolkienCharacter, Race&gt;() {
-   *    {@literal @}Override
-   *    public Race apply(TolkienCharacter input) {
-   *        return input.getRace();
-   *    }
-   * }
-   *
    * // fellowship has hobbitses, right, my presioussss?
    * assertThat(fellowshipOfTheRing).extracting(TolkienCharacter::getRace).contains(HOBBIT);</code></pre>
    *
@@ -1341,23 +1333,19 @@ private <V> AbstractListAssert<?, List<? extends V>, V, ObjectAssert<V>> newList
    * CartoonCharacter lisa = new CartoonCharacter("Lisa Simpson");
    * CartoonCharacter maggie = new CartoonCharacter("Maggie Simpson");
    * CartoonCharacter homer = new CartoonCharacter("Homer Simpson");
-   * homer.addChildren(bart, lisa, maggie);
+   * homer.getChildren().add(bart);
+   * homer.getChildren().add(lisa);
+   * homer.getChildren().add(maggie);
    *
    * CartoonCharacter pebbles = new CartoonCharacter("Pebbles Flintstone");
    * CartoonCharacter fred = new CartoonCharacter("Fred Flintstone");
    * fred.getChildren().add(pebbles);
    *
-   * Function&lt;CartoonCharacter, List&lt;CartoonCharacter&gt;&gt; childrenOf = new Function&lt;CartoonChildren, List&lt;CartoonChildren&gt;&gt;() {
-   *    {@literal @}Override
-   *    public List&lt;CartoonChildren&gt; extract(CartoonCharacter input) {
-   *        return input.getChildren();
-   *    }
-   * }
+   * List&lt;CartoonCharacter&gt; parents = list(homer, fred);
    *
-   * List&lt;CartoonCharacter&gt; parents = newArrayList(homer, fred);
-   * // check children
-   * assertThat(parent).flatExtracting(CartoonCharacter::getChildren)
-   *                   .containsOnly(bart, lisa, maggie, pebbles);</code></pre>
+   * // check children property which is a List&lt;CartoonCharacter&gt;
+   * assertThat(parents).flatExtracting(CartoonCharacter::getChildren)
+   *                    .containsOnly(bart, lisa, maggie, pebbles);</code></pre>
    *
    * The order of extracted values is consistent with both the order of the collection itself, as well as the extracted
    * collections.
@@ -1374,7 +1362,7 @@ public <V> AbstractListAssert<?, List<? extends V>, V, ObjectAssert<V>> flatExtr
 
   /**
    * Extract the Iterable values from Iterable's elements under test by applying an Iterable extracting function (which
-   * might throw an exception) on them and concatenating the result lists. The returned iterable becomes a new object
+   * might throw a checked exception) on them and concatenating the result lists. The returned iterable becomes a new object
    * under test.
    * <p>
    * It allows testing the results of extracting values that are represented by Iterables.
@@ -1384,20 +1372,19 @@ public <V> AbstractListAssert<?, List<? extends V>, V, ObjectAssert<V>> flatExtr
    * CartoonCharacter lisa = new CartoonCharacter("Lisa Simpson");
    * CartoonCharacter maggie = new CartoonCharacter("Maggie Simpson");
    * CartoonCharacter homer = new CartoonCharacter("Homer Simpson");
-   * homer.addChildren(bart, lisa, maggie);
+   * homer.getChildren().add(bart);
+   * homer.getChildren().add(lisa);
+   * homer.getChildren().add(maggie);
    *
    * CartoonCharacter pebbles = new CartoonCharacter("Pebbles Flintstone");
    * CartoonCharacter fred = new CartoonCharacter("Fred Flintstone");
    * fred.getChildren().add(pebbles);
    *
-   * List&lt;CartoonCharacter&gt; parents = newArrayList(homer, fred);
-   * // check children
-   * assertThat(parent).flatExtracting((ThrowingExtractor&lt;CartoonCharacter, List&lt;CartoonCharacter&gt;, Exception&gt;)input -&gt; {
-   *   if (input.getChildren().size() == 0) {
-   *     throw new Exception("no children");
-   *   }
-   *   return input.getChildren();
-   * }).containsOnly(bart, lisa, maggie, pebbles);</code></pre>
+   * List&lt;CartoonCharacter&gt; parents = list(homer, fred);
+   *
+   * // check children property where getChildren() can throw an Exception!
+   * assertThat(parents).flatExtracting(CartoonCharacter::getChildren)
+   *                    .containsOnly(bart, lisa, maggie, pebbles);</code></pre>
    *
    * The order of extracted values is consistent with both the order of the collection itself, as well as the extracted
    * collections.
@@ -1510,14 +1497,17 @@ public <EXCEPTION extends Exception> AbstractListAssert<?, List<? extends Object
    * CartoonCharacter lisa = new CartoonCharacter("Lisa Simpson");
    * CartoonCharacter maggie = new CartoonCharacter("Maggie Simpson");
    * CartoonCharacter homer = new CartoonCharacter("Homer Simpson");
-   * homer.addChildren(bart, lisa, maggie);
+   * homer.getChildren().add(bart);
+   * homer.getChildren().add(lisa);
+   * homer.getChildren().add(maggie);
    *
    * CartoonCharacter pebbles = new CartoonCharacter("Pebbles Flintstone");
    * CartoonCharacter fred = new CartoonCharacter("Fred Flintstone");
    * fred.getChildren().add(pebbles);
    *
-   * List&lt;CartoonCharacter&gt; parents = newArrayList(homer, fred);
-   * // check children
+   * List&lt;CartoonCharacter&gt; parents = list(homer, fred);
+   *
+   * // check children which is a List&lt;CartoonCharacter&gt;
    * assertThat(parents).flatExtracting("children")
    *                    .containsOnly(bart, lisa, maggie, pebbles);</code></pre>
    *
@@ -1580,7 +1570,7 @@ public AbstractListAssert<?, List<? extends Object>, Object, ObjectAssert<Object
    *
    * // let's verify 'name', 'age' and Race of some TolkienCharacter in fellowshipOfTheRing :
    * assertThat(fellowshipOfTheRing).extracting(TolkienCharacter::getName,
-   *                                            character &gt; character.getAge(),
+   *                                            character -&gt; character.getAge(),
    *                                            TolkienCharacter::getRace)
    *                                .containsOnly(tuple(&quot;Frodo&quot;, 33, HOBBIT),
    *                                              tuple(&quot;Sam&quot;, 38, HOBBIT),

src/main/java/org/assertj/core/api/AbstractLocalDateTimeAssert.java

@@ -332,12 +332,12 @@ public SELF isNotIn(String... dateTimesAsString) {
    * Example:
    * <pre><code class='java'> LocalDateTime actual = LocalDateTime.now(Clock.systemUTC());
    *
-   * // assertion will pass as it is executed less than one second after actual was built
+   * // assertion will pass as if executed less than one second after actual was built
    * assertThat(actual).isCloseToUtcNow(within(1, ChronoUnit.SECONDS));
    *
    * // assertion will fail
    * assertThat(actual.plusSeconds(2)).isCloseToUtcNow(within(1, ChronoUnit.SECONDS));</code></pre>
-   * 
+   *
    * @param offset The offset used for comparison
    * @return this assertion object
    * @throws NullPointerException if {@code offset} parameter is {@code null}.

src/main/java/org/assertj/core/api/AbstractMapAssert.java

@@ -639,6 +639,10 @@ public SELF containsExactlyEntriesOf(Map<? extends K, ? extends V> map) {
    * assertThat(ringBearers).containsExactlyInAnyOrderEntriesOf(newLinkedHashMap(entry(nenya, galadriel),
    *                                                                             entry(narya, gandalf),
    *                                                                             entry(oneRing, frodo)));
+   * // assertion will fail as actual does not contain all expected entries
+   * assertThat(ringBearers).containsExactlyInAnyOrderEntriesOf(newLinkedHashMap(entry(oneRing, frodo),
+   *                                                                             entry(nenya, galadriel),
+   *                                                                             entry(vilya, elrond)));
    * // assertion will fail as actual and expected have different sizes
    * assertThat(ringBearers).containsExactlyInAnyOrderEntriesOf(newLinkedHashMap(entry(oneRing, frodo),
    *                                                                             entry(nenya, galadriel),

src/main/java/org/assertj/core/api/AbstractObjectAssert.java

@@ -712,6 +712,7 @@ public AbstractListAssert<?, List<?>, Object, ObjectAssert<Object>> extracting(@
    * assertThat(frodo).extracting(TolkienCharacter::getName)
    *                  .startsWith(&quot;Fro&quot;);</code></pre>
    *
+   * @param <T> the expected extracted value type.
    * @param extractor the extractor function used to extract the value from the object under test.
    * @return a new {@link ObjectAssert} instance whose object under test is the extracted value
    *

src/main/java/org/assertj/core/api/AbstractOffsetDateTimeAssert.java

@@ -253,12 +253,12 @@ public SELF isAfter(String offsetDateTimeAsString) {
    * Example:
    * <pre><code class='java'> OffsetDateTime actual = OffsetDateTime.now(Clock.systemUTC());
    *
-   * // assertion will pass as it is executed less than one second after actual was built
+   * // assertion will pass as if executed less than one second after actual was built
    * assertThat(actual).isCloseToUtcNow(within(1, ChronoUnit.SECONDS));
    *
    * // assertion will fail
    * assertThat(actual.plusSeconds(2)).isCloseToUtcNow(within(1, ChronoUnit.SECONDS));</code></pre>
-   * 
+   *
    * @param offset The offset used for comparison
    * @return this assertion object
    * @throws NullPointerException if {@code offset} parameter is {@code null}.

src/test/java/org/assertj/core/api/recursive/comparison/RecursiveComparisonAssert_isEqualTo_ignoringCollectionOrder_Test.java

@@ -41,7 +41,6 @@ public void should_pass_for_objects_with_the_same_data_when_collection_order_is_
                       .isEqualTo(expected);
   }
 
-  @SuppressWarnings("unused")
   private static Stream<Arguments> should_pass_for_objects_with_the_same_data_when_collection_order_is_ignored_source() {
     FriendlyPerson friendlyPerson1 = friend("Sherlock Holmes");
     friendlyPerson1.friends.add(friend("Dr. John Watson"));