Document benefits of messageSupplier in Assertions

Issue: #3153

Author: chris-carneiro

documentation/src/docs/asciidoc/user-guide/writing-tests.adoc

@@ -293,6 +293,14 @@ JUnit Jupiter comes with many of the assertion methods that JUnit 4 has and adds
 that lend themselves well to being used with Java 8 lambdas. All JUnit Jupiter assertions
 are `static` methods in the `{Assertions}` class.
 
+Assertion methods can accept an optional third parameter, which can be either a `String` or a `Supplier<String>`.
+When using a `Supplier<String>` (e.g., a lambda expression) as the message supplier,
+the message is evaluated lazily.
+
+Lazily evaluating the assertion message can provide a performance benefit,
+especially if the message construction is complex or time-consuming,
+as it is only evaluated when the assertion fails.
+
 [source,java,indent=0]
 ----
 include::{testDir}/example/AssertionsDemo.java[tags=user_guide]

documentation/src/test/java/example/AssertionsDemo.java

@@ -41,8 +41,9 @@ void standardAssertions() {
 assertEquals(2, calculator.add(1, 1));
 assertEquals(4, calculator.multiply(2, 2),
 "The optional failure message is now the last parameter");
-assertTrue('a' < 'b', () -> "Assertion messages can be lazily evaluated -- "
-+ "to avoid constructing complex messages unnecessarily.");
+
+// Lazily evaluates generateFailureMessage('a','b').
+assertTrue('a' < 'b', () -> generateFailureMessage('a','b'));
 }
 
 @Test
@@ -160,6 +161,10 @@ private static String greeting() {
 return "Hello, World!";
 }
 
+private static String generateFailureMessage(char a, char b) {
+return "Assertion messages can be lazily evaluated -- "
++ "to avoid constructing complex messages unnecessarily." + (a < b);
+}
 }
 // end::user_guide[]
 // @formatter:on