Improve layout and grouping for DisplyNameGenerator examples

junit-team · Mar 2, 2025 · 305657c · 305657c
1 parent e84236d
commit 305657c
Show file tree

Hide file tree

Showing 2 changed files with 33 additions and 16 deletions.
diff --git a/documentation/src/docs/asciidoc/user-guide/writing-tests.adoc b/documentation/src/docs/asciidoc/user-guide/writing-tests.adoc
@@ -228,26 +228,42 @@ ones available in Jupiter:
 |===
 
 ======
-Note that for `IndicativeSentences`, you can customize the separator and the underlying
-generator by using `@IndicativeSentencesGeneration` as shown in the following example.
+The following example demonstrates the use of the `ReplaceUnderscores` display name
+generator.
 
 [source,java,indent=0]
 ----
-include::{testDir}/example/DisplayNameGeneratorDemo.java[tags=user_guide]
+include::{testDir}/example/DisplayNameGeneratorDemo.java[tags=user_guide_replace_underscores]
 ----
 
-Running the above `DisplayNameGeneratorDemo` test class results in the following display names.
+Running the above `A_year_is_not_supported` test class results in the following display names.
 
 ```
-+-- DisplayNameGeneratorDemo [OK]
-  +-- A year is not supported [OK]
-  | '-- if it is zero [OK]
-  | +-- A negative value for year is not supported by the leap year computation. [OK]
-  | | +-- For example, year -1 is not supported. [OK]
-  | | '-- For example, year -4 is not supported. [OK]
-  '-- A year is a leap year [OK]
-    +-- A year is a leap year -> if it is divisible by 4 but not by 100 [OK]
-    '-- A year is a leap year -> if it is one of the following years [OK]
+A year is not supported [OK]
+   +-- if it is zero [OK]
+   '-- A negative value for year is not supported by the leap year computation. [OK]
+      +-- For example, year -1 is not supported. [OK]
+      '-- For example, year -4 is not supported. [OK]
+```
+======
+
+======
+With the `IndicativeSentences` display name generator, you can customize the separator and
+the underlying generator by using `@IndicativeSentencesGeneration` as shown in the
+following example.
+
+[source,java,indent=0]
+----
+include::{testDir}/example/DisplayNameGeneratorDemo.java[tags=user_guide_indicative_sentences]
+----
+
+Running the above `A_year_is_a_leap_year` test class results in the following display
+names.
+
+```
+A year is a leap year [OK]
+   +-- A year is a leap year -> if it is divisible by 4 but not by 100 [OK]
+   '-- A year is a leap year -> if it is one of the following years [OK]
       +-- Year 2016 is a leap year. [OK]
       +-- Year 2020 is a leap year. [OK]
       '-- Year 2048 is a leap year. [OK]

diff --git a/documentation/src/test/java/example/DisplayNameGeneratorDemo.java b/documentation/src/test/java/example/DisplayNameGeneratorDemo.java
@@ -10,8 +10,6 @@
 
 package example;
 
-// tag::user_guide[]
-
 import org.junit.jupiter.api.DisplayName;
 import org.junit.jupiter.api.DisplayNameGeneration;
 import org.junit.jupiter.api.DisplayNameGenerator;
@@ -25,6 +23,7 @@
 class DisplayNameGeneratorDemo {
 
 	@Nested
+	// tag::user_guide_replace_underscores[]
 	@DisplayNameGeneration(DisplayNameGenerator.ReplaceUnderscores.class)
 	class A_year_is_not_supported {
 
@@ -39,8 +38,10 @@ void if_it_is_negative(int year) {
 		}
 
 	}
+	// end::user_guide_replace_underscores[]
 
 	@Nested
+	// tag::user_guide_indicative_sentences[]
 	@IndicativeSentencesGeneration(separator = " -> ", generator = ReplaceUnderscores.class)
 	class A_year_is_a_leap_year {
 
@@ -54,6 +55,6 @@ void if_it_is_one_of_the_following_years(int year) {
 		}
 
 	}
+	// end::user_guide_indicative_sentences[]
 
 }
-// end::user_guide[]