Add Javadoc

junit-jupiter-api/src/main/java/org/junit/jupiter/api/AssertionFailureBuilder.java

@@ -10,13 +10,25 @@
 
 package org.junit.jupiter.api;
 
+import static org.apiguardian.api.API.Status.STABLE;
 import static org.junit.jupiter.api.AssertionUtils.getCanonicalName;
 
 import java.util.function.Supplier;
 
+import org.apiguardian.api.API;
 import org.junit.platform.commons.util.StringUtils;
 import org.opentest4j.AssertionFailedError;
 
+/**
+ * Builder for {@link AssertionFailedError AssertionFailedErrors}.
+ * <p>
+ * Using this builder ensures consistency in how failure message are formatted
+ * within JUnit Jupiter and for custom user-defined assertions.
+ *
+ * @see AssertionFailedError
+ * @since 5.9
+ */
+@API(status = STABLE, since = "5.9")
 public class AssertionFailureBuilder {
 
 	private Object message;
@@ -27,49 +39,105 @@ public class AssertionFailureBuilder {
 	private String reason;
 	private boolean includeValuesInMessage = true;
 
+	/**
+	 * Create a new {@code AssertionFailureBuilder}.
+	 */
 	public static AssertionFailureBuilder assertionFailure() {
 		return new AssertionFailureBuilder();
 	}
 
 	private AssertionFailureBuilder() {
 	}
 
+	/**
+	 * Set the user-defined message of the assertion.
+	 * <p>
+	 * The {@code message} may be passed as a {@link Supplier} or plain
+	 * {@link String}. If any other type is passed, it is converted to
+	 * {@code String} as per {@link StringUtils#nullSafeToString(Object)}.
+	 *
+	 * @param message the user-defined failure message; may be {@code null}
+	 * @return this builder for method chaining
+	 */
 	public AssertionFailureBuilder message(Object message) {
 		this.message = message;
 		return this;
 	}
 
+	/**
+	 * Set the reason why the assertion failed.
+	 *
+	 * @param reason the failure reason; may be {@code null}
+	 * @return this builder for method chaining
+	 */
 	public AssertionFailureBuilder reason(String reason) {
 		this.reason = reason;
 		return this;
 	}
 
+	/**
+	 * Set the cause of the assertion failure.
+	 *
+	 * @param cause the failure cause; may be {@code null}
+	 * @return this builder for method chaining
+	 */
 	public AssertionFailureBuilder cause(Throwable cause) {
 		this.cause = cause;
 		return this;
 	}
 
+	/**
+	 * Set the expected value of the assertion.
+	 *
+	 * @param expected the expected value; may be {@code null}
+	 * @return this builder for method chaining
+	 */
 	public AssertionFailureBuilder expected(Object expected) {
 		this.mismatch = true;
 		this.expected = expected;
 		return this;
 	}
 
+	/**
+	 * Set the actual value of the assertion.
+	 *
+	 * @param actual the actual value; may be {@code null}
+	 * @return this builder for method chaining
+	 */
 	public AssertionFailureBuilder actual(Object actual) {
 		this.mismatch = true;
 		this.actual = actual;
 		return this;
 	}
 
+	/**
+	 * Set whether to include the actual and expected values in the generated
+	 * failure message.
+	 *
+	 * @param includeValuesInMessage whether to include the actual and expected
+	 *                               values
+	 * @return this builder for method chaining
+	 */
 	public AssertionFailureBuilder includeValuesInMessage(boolean includeValuesInMessage) {
 		this.includeValuesInMessage = includeValuesInMessage;
 		return this;
 	}
 
+	/**
+	 * Build the {@link AssertionFailedError AssertionFailedError} and throw it.
+	 *
+	 * @throws AssertionFailedError always
+	 */
 	public void buildAndThrow() throws AssertionFailedError {
 		throw build();
 	}
 
+	/**
+	 * Build the {@link AssertionFailedError AssertionFailedError} without
+	 * throwing it.
+	 *
+	 * @return the built assertion failure
+	 */
 	public AssertionFailedError build() {
 		String reason = nullSafeGet(this.reason);
 		if (mismatch && includeValuesInMessage) {
@@ -90,9 +158,9 @@ private static String nullSafeGet(Object messageOrSupplier) {
 		}
 		if (messageOrSupplier instanceof Supplier) {
 			Object message = ((Supplier<?>) messageOrSupplier).get();
-			return message == null ? null : message.toString();
+			return StringUtils.nullSafeToString(message);
 		}
-		return String.valueOf(messageOrSupplier);
+		return StringUtils.nullSafeToString(messageOrSupplier);
 	}
 
 	private static String buildPrefix(String message) {