From a44ff4ec793f2295be5c7bdf4789b8b0a3b157bf Mon Sep 17 00:00:00 2001 From: Joel Costigliola Date: Sun, 23 Aug 2020 15:31:23 +1200 Subject: [PATCH] Javadoc improvements --- .../core/api/AbstractInputStreamAssert.java | 4 +++ .../core/api/AbstractIterableAssert.java | 8 +++--- .../core/api/AbstractSoftAssertions.java | 26 ++++++++++++++++--- .../java/org/assertj/core/api/Assertions.java | 2 +- 4 files changed, 31 insertions(+), 9 deletions(-) diff --git a/src/main/java/org/assertj/core/api/AbstractInputStreamAssert.java b/src/main/java/org/assertj/core/api/AbstractInputStreamAssert.java index c4b7a24861..6c7b776ff2 100644 --- a/src/main/java/org/assertj/core/api/AbstractInputStreamAssert.java +++ b/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. *

+ * Warning: this will consume the first byte of the {@code InputStream}. + *

* Example: *

 // 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.
    * 

+ * Warning: this will consume the first byte of the {@code InputStream}. + *

* Example: *

 // assertion will pass
    * assertThat(new ByteArrayInputStream(new byte[] {0xa})).isNotEmpty());
diff --git a/src/main/java/org/assertj/core/api/AbstractIterableAssert.java b/src/main/java/org/assertj/core/api/AbstractIterableAssert.java
index df5800fefb..6a6e313b90 100644
--- a/src/main/java/org/assertj/core/api/AbstractIterableAssert.java
+++ b/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 hasSize(1).first(assertFactory).
    * 

* Example: use of {@code String} assertions after {@code singleElement(as(STRING)} - *

 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
+   * 
 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<String> babySimpsons = list("Maggie");
    *
diff --git a/src/main/java/org/assertj/core/api/AbstractSoftAssertions.java b/src/main/java/org/assertj/core/api/AbstractSoftAssertions.java
index 66d48ff70a..688a95ed2d 100644
--- a/src/main/java/org/assertj/core/api/AbstractSoftAssertions.java
+++ b/src/main/java/org/assertj/core/api/AbstractSoftAssertions.java
@@ -37,12 +37,30 @@ public AbstractSoftAssertions() {
    * 

* Example: *

 SoftAssertions softly = new SoftAssertions();
-   *
+   * StringBuilder reportBuilder = new StringBuilder(format("Assertions report:%n"));
+  
    * // register our callback
-   * softly.setAfterAssertionErrorCollected(error -> System.out.println(error));
+   * softly.setAfterAssertionErrorCollected(error -> 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");
+ * // 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);
+ *

+ * resulting {@code reportBuilder}: + *

 Assertions report:
+   * ------------------
+   * Expecting:
+   *  <"The Beatles">
+   * to be equal to:
+   *  <"The Rolling Stones">
+   * but was not.
+   * ------------------
+   * Expecting:
+   *  <123>
+   * to be equal to:
+   *  <456>
+   * but was not.
*

* 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)}. diff --git a/src/main/java/org/assertj/core/api/Assertions.java b/src/main/java/org/assertj/core/api/Assertions.java index 9afb2929c3..1348fd49d3 100644 --- a/src/main/java/org/assertj/core/api/Assertions.java +++ b/src/main/java/org/assertj/core/api/Assertions.java @@ -1372,7 +1372,7 @@ public static ThrowableTypeAssert assertThatExceptionOf * Entry point to check that no exception of any type is thrown by a given {@code throwingCallable}. *

* Example: - *

assertThatNoException().isThrownBy(() -> { System.out.println("OK"); });
+ *
assertThatNoException().isThrownBy(() -> System.out.println("OK"));
* * This method is more or less the same of {@code assertThatCode(...).doesNotThrowAnyException();} but in a more natural way. *