Javadoc improvements

Author: joel-costigliola

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

@@ -82,6 +82,8 @@ public SELF hasSameContentAs(InputStream expected) {
   /**
    * Verifies that the content of the actual {@code InputStream} is empty.
    * <p>
+   * <b>Warning: this will consume the first byte of the {@code InputStream}.</b>
+   * <p>
    * Example:
    * <pre><code class='java'> // assertion will pass
    * assertThat(new ByteArrayInputStream(new byte[] {})).isEmpty());
@@ -103,6 +105,8 @@ public SELF isEmpty() {
   /**
    * Verifies that the content of the actual {@code InputStream} is not empty.
    * <p>
+   * <b>Warning: this will consume the first byte of the {@code InputStream}.</b>
+   * <p>
    * Example:
    * <pre><code class='java'> // assertion will pass
    * assertThat(new ByteArrayInputStream(new byte[] {0xa})).isNotEmpty());

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

@@ -2888,7 +2888,7 @@ private ELEMENT_ASSERT internalElement(int index) {
    * // InstanceOfAssertFactories.STRING is an AssertFactory for String assertions
    * assertThat(babySimpsons, InstanceOfAssertFactories.STRING).singleElement()
    *                                                           .startsWith("Mag");
-   * // better readability with static import InstanceOfAssertFactories.STRING and Assertions.as
+   * // better readability with import static InstanceOfAssertFactories.STRING and Assertions.as
    * assertThat(babySimpsons, as(STRING)).singleElement()
    *                                     .startsWith("Mag");
    *
@@ -2916,9 +2916,9 @@ public ELEMENT_ASSERT singleElement() {
    * This is a shorthand for <code>hasSize(1).first(assertFactory)</code>.
    * <p>
    * Example: use of {@code String} assertions after {@code singleElement(as(STRING)}
-   * <pre><code class='java'> static import org.assertj.core.api.InstanceOfAssertFactories.STRING;
-   * static import org.assertj.core.api.InstanceOfAssertFactories.INTEGER;
-   * static import org.assertj.core.api.Assertions.as; // syntactic sugar
+   * <pre><code class='java'> import static org.assertj.core.api.InstanceOfAssertFactories.STRING;
+   * import static org.assertj.core.api.InstanceOfAssertFactories.INTEGER;
+   * import static org.assertj.core.api.Assertions.as; // syntactic sugar
    *
    * List&lt;String&gt; babySimpsons = list("Maggie");
    *

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

@@ -37,12 +37,30 @@ public AbstractSoftAssertions() {
    * <p>
    * Example:
    * <pre><code class='java'> SoftAssertions softly = new SoftAssertions();
-   *
+   * StringBuilder reportBuilder = new StringBuilder(format("Assertions report:%n"));
+  
    * // register our callback
-   * softly.setAfterAssertionErrorCollected(error -&gt; System.out.println(error));
+   * softly.setAfterAssertionErrorCollected(error -&gt; reportBuilder.append(String.format("------------------%n%s%n", error.getMessage())));
    *
-   * // the AssertionError corresponding to this failing assertion is printed to the console.
-   * softly.assertThat("The Beatles").isEqualTo("The Rolling Stones");</code></pre>
+   * // the AssertionError corresponding to the failing assertions are registered in the report
+   * softly.assertThat("The Beatles").isEqualTo("The Rolling Stones");
+   * softly.assertThat(123).isEqualTo(123)
+   *                       .isEqualTo(456);</code></pre>
+   * <p>
+   * resulting {@code reportBuilder}:
+   * <pre><code class='java'> Assertions report:
+   * ------------------
+   * Expecting:
+   *  &lt;"The Beatles"&gt;
+   * to be equal to:
+   *  &lt;"The Rolling Stones"&gt;
+   * but was not.
+   * ------------------
+   * Expecting:
+   *  &lt;123&gt;
+   * to be equal to:
+   *  &lt;456&gt;
+   * but was not.</code></pre>
    * <p>
    * Alternatively, if you have defined your own SoftAssertions subclass and inherited from {@link AbstractSoftAssertions},
    * the only thing you have to do is to override {@link AfterAssertionErrorCollected#onAssertionErrorCollected(AssertionError)}.

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

@@ -1372,7 +1372,7 @@ public static <T extends Throwable> ThrowableTypeAssert<T> assertThatExceptionOf
    * Entry point to check that no exception of any type is thrown by a given {@code throwingCallable}.
    * <p>
    * Example:
-   * <pre><code class='java'>assertThatNoException().isThrownBy(() -&gt; { System.out.println("OK"); });</code></pre>
+   * <pre><code class='java'>assertThatNoException().isThrownBy(() -&gt; System.out.println("OK"));</code></pre>
    *
    * This method is more or less the same of {@code assertThatCode(...).doesNotThrowAnyException();} but in a more natural way.
    *