Polishing in FragmentsRendering

See gh-33194

spring-webflux/src/main/java/org/springframework/web/reactive/result/view/FragmentsRendering.java

@@ -32,11 +32,11 @@ import org.springframework.lang.Nullable;
 import org.springframework.util.Assert;
 
 /**
- * Public API for HTML rendering from a collection or from a stream of
+ * Public API for HTML rendering of a collection of fragments each with a view
- * {@link Fragment}s each with its own view and model. For use with
+ * and independent model. For use with frontends technologies such as
- * view technologies such as <a href="https://htmx.org/">htmx</a> where multiple
+ * <a href="https://htmx.org/">htmx</a> where multiple page fragments may be
- * page fragments may be rendered in a single response. Supported as a return
+ * rendered in one response. Supported as a return value from Spring WebFlux
- * value from a WebFlux controller method.
+ * controller methods.
  *
  * <p>For full page rendering with a single model and view, use {@link Rendering}.
  *
@@ -74,8 +74,8 @@ public interface FragmentsRendering {
 	}
 
 	/**
-	 * Create a builder and add a fragment with a view name only, also
+	 * Variant of {@link #with(String, Map)} with a view name only, but also
-	 * inheriting model attributes from the model for the request.
+	 * inheriting model attributes from the shared model for the request.
 	 * @param viewName the name of the view for the fragment
 	 * @return this builder
 	 */
@@ -84,14 +84,20 @@ public interface FragmentsRendering {
 	}
 
 	/**
-	 * Create a builder to render with a collection of Fragments.
+	 * Variant of {@link #with(String, Map)} with a collection of fragments.
+	 * @param fragments the fragments to add; each fragment also inherits model
+	 * attributes from the shared model for the request
+	 * @return the created builder
 	 */
 	static Builder withCollection(Collection<Fragment> fragments) {
 		return new DefaultFragmentsRenderingBuilder(fragments);
 	}
 
 	/**
-	 * Create a builder to render with a {@link Publisher} of Fragments.
+	 * Variant of {@link #with(String, Map)} with a {@link Publisher} of fragments.
+	 * @param fragmentsPublisher the fragments to add; each fragment also
+	 * inherits model attributes from the shared model for the request
+	 * @return the created builder
 	 */
 	static <P extends Publisher<Fragment>> Builder withPublisher(P fragmentsPublisher) {
 		return new DefaultFragmentsRenderingBuilder(fragmentsPublisher);
@@ -126,7 +132,7 @@ public interface FragmentsRendering {
 		Builder status(HttpStatusCode status);
 
 		/**
-		 * Add the given, single header value under the given name.
+		 * Add one or more header values under the given name.
 		 * @param headerName  the header name
 		 * @param headerValues the header value(s)
 		 * @return this builder
@@ -151,15 +157,16 @@ public interface FragmentsRendering {
 		Builder fragment(String viewName, Map<String, Object> model);
 
 		/**
-		 * Add a fragment with a view name only, inheriting model attributes from
+		 * Variant of {@link #fragment(String, Map)} with a view name only, where
-		 * the model for the request.
+		 * the fragment model also inherits model attributes from the shared
+		 * model for the request.
 		 * @param viewName the name of the view for the fragment
 		 * @return this builder
 		 */
 		Builder fragment(String viewName);
 
 		/**
-		 * Add a fragment.
+		 * Variant of {@link #fragment(String, Map)} with a {@link Fragment}.
 		 * @param fragment the fragment to add
 		 * @return this builder
 		 */

spring-webflux/src/test/java/org/springframework/web/reactive/result/view/FragmentViewResolutionResultHandlerTests.java

@@ -22,6 +22,7 @@ import java.util.Locale;
 import java.util.Map;
 import java.util.stream.Stream;
 
+import org.junit.jupiter.api.Test;
 import org.junit.jupiter.params.ParameterizedTest;
 import org.junit.jupiter.params.provider.Arguments;
 import org.junit.jupiter.params.provider.MethodSource;
@@ -54,25 +55,21 @@ import static org.springframework.web.testfixture.method.ResolvableMethod.on;
  */
 public class FragmentViewResolutionResultHandlerTests {
 
+	private static final Fragment fragment1 = Fragment.create("fragment1", Map.of("foo", "Foo"));
+
+	private static final Fragment fragment2 = Fragment.create("fragment2", Map.of("bar", "Bar"));
+
+
 	static Stream<Arguments> arguments() {
-		Fragment f1 = Fragment.create("fragment1", Map.of("foo", "Foo"));
+		Flux<Fragment> fragmentFlux = Flux.just(fragment1, fragment2).subscribeOn(Schedulers.boundedElastic());
-		Fragment f2 = Fragment.create("fragment2", Map.of("bar", "Bar"));
 		return Stream.of(
-				Arguments.of(
+				Arguments.of(FragmentsRendering.withPublisher(fragmentFlux).build(),
-						FragmentsRendering.withPublisher(Flux.just(f1, f2).subscribeOn(Schedulers.boundedElastic()))
-								.headers(headers -> headers.setContentType(MediaType.TEXT_HTML))
-								.build(),
 						on(Handler.class).resolveReturnType(FragmentsRendering.class)),
-				Arguments.of(
+				Arguments.of(FragmentsRendering.withCollection(List.of(fragment1, fragment2)).build(),
-						FragmentsRendering.withCollection(List.of(f1, f2))
-								.headers(headers -> headers.setContentType(MediaType.TEXT_HTML))
-								.build(),
 						on(Handler.class).resolveReturnType(FragmentsRendering.class)),
-				Arguments.of(
+				Arguments.of(fragmentFlux,
-						Flux.just(f1, f2).subscribeOn(Schedulers.boundedElastic()),
 						on(Handler.class).resolveReturnType(Flux.class, Fragment.class)),
-				Arguments.of(
+				Arguments.of(List.of(fragment1, fragment2),
-						List.of(f1, f2),
 						on(Handler.class).resolveReturnType(List.class, Fragment.class)));
 	}
 
@@ -107,14 +104,14 @@ public class FragmentViewResolutionResultHandlerTests {
 	}
 
 
-	@SuppressWarnings("unused")
+	@SuppressWarnings({"unused", "DataFlowIssue"})
 	private static class Handler {
 
-		FragmentsRendering rendering() { return null; }
+		FragmentsRendering render() { return null; }
 
-		Flux<Fragment> fragmentFlux() { return null; }
+		Flux<Fragment> renderFlux() { return null; }
 
-		List<Fragment> fragmentList() { return null; }
+		List<Fragment> renderList() { return null; }
 
 	}
 

spring-webmvc/src/main/java/org/springframework/web/servlet/view/FragmentsRendering.java

@@ -27,11 +27,11 @@ import org.springframework.web.servlet.ModelAndView;
 import org.springframework.web.servlet.SmartView;
 
 /**
- * Public API for HTML rendering a collection fragments each with its own view
+ * Public API for HTML rendering of a collection of fragments each with a view
- * and model. For use with view technologies such as
+ * and independent model. For use with frontends technologies such as
  * <a href="https://htmx.org/">htmx</a> where multiple page fragments may be
- * rendered in a single response. Supported as a return value from a Spring MVC
+ * rendered in one response. Supported as a return value from Spring MVC
- * controller method.
+ * controller methods.
  *
  * @author Rossen Stoyanchev
  * @since 6.2
@@ -51,8 +51,7 @@ public interface FragmentsRendering extends SmartView {
 
 
 	/**
-	 * Create a builder for {@link FragmentsRendering}, adding a fragment with
+	 * Create a builder and add a fragment with a view name and a model.
-	 * the given view name and model.
 	 * @param viewName the name of the view for the fragment
 	 * @param model attributes for the fragment in addition to model
 	 * attributes inherited from the shared model for the request
@@ -96,7 +95,7 @@ public interface FragmentsRendering extends SmartView {
 		Builder status(HttpStatusCode status);
 
 		/**
-		 * Add the given, single header value under the given name.
+		 * Add one or more header values under the given name.
 		 * @param headerName  the header name
 		 * @param headerValues the header value(s)
 		 * @return this builder
@@ -121,15 +120,15 @@ public interface FragmentsRendering extends SmartView {
 		Builder fragment(String viewName, Map<String, Object> model);
 
 		/**
-		 * Add a fragment with a view name only, inheriting model attributes from
+		 * Variant of {@link #fragment(String, Map)} with a view name only, but
-		 * the model for the request.
+		 * also inheriting model attributes from the shared model for the request.
 		 * @param viewName the name of the view for the fragment
 		 * @return this builder
 		 */
 		Builder fragment(String viewName);
 
 		/**
-		 * Add a fragment.
+		 * Variant of {@link #fragment(String, Map)} with a {@link ModelAndView}.
 		 * @param fragment the fragment to add; the fragment also inherits model
 		 * attributes from the shared model for the request
 		 * @return this builder
@@ -137,7 +136,7 @@ public interface FragmentsRendering extends SmartView {
 		Builder fragment(ModelAndView fragment);
 
 		/**
-		 * Add a collection of fragments.
+		 * Variant of {@link #fragment(String, Map)} with a collection of {@link ModelAndView}s.
 		 * @param fragments the fragments to add; each fragment also inherits model
 		 * attributes from the shared model for the request
 		 * @return this builder