From 1fd0b8730be944075cf06326d92c1cee98079bf7 Mon Sep 17 00:00:00 2001 From: rstoyanchev Date: Tue, 26 Nov 2024 18:26:54 +0000 Subject: [PATCH] Improve Javadoc of FragmentsRendering --- .../web/reactive/result/view/Fragment.java | 4 +- .../result/view/FragmentsRendering.java | 48 ++++++++++--------- .../web/servlet/view/FragmentsRendering.java | 44 +++++++++-------- 3 files changed, 50 insertions(+), 46 deletions(-) diff --git a/spring-webflux/src/main/java/org/springframework/web/reactive/result/view/Fragment.java b/spring-webflux/src/main/java/org/springframework/web/reactive/result/view/Fragment.java index f835b3f680..f999f5ae32 100644 --- a/spring-webflux/src/main/java/org/springframework/web/reactive/result/view/Fragment.java +++ b/spring-webflux/src/main/java/org/springframework/web/reactive/result/view/Fragment.java @@ -26,9 +26,7 @@ import org.springframework.util.Assert; import org.springframework.util.CollectionUtils; /** - * Container for a model and a view for use with {@link FragmentsRendering} and - * multi-view rendering. For full page rendering with a single model and view, - * use {@link Rendering}. + * Container for a model and a view pair. For use with {@link FragmentsRendering}. * * @author Rossen Stoyanchev * @since 6.2 diff --git a/spring-webflux/src/main/java/org/springframework/web/reactive/result/view/FragmentsRendering.java b/spring-webflux/src/main/java/org/springframework/web/reactive/result/view/FragmentsRendering.java index 1a7ad5bcc1..29728917ac 100644 --- a/spring-webflux/src/main/java/org/springframework/web/reactive/result/view/FragmentsRendering.java +++ b/spring-webflux/src/main/java/org/springframework/web/reactive/result/view/FragmentsRendering.java @@ -32,13 +32,16 @@ import org.springframework.lang.Nullable; import org.springframework.util.Assert; /** - * Public API for HTML rendering of a collection of fragments each with a view - * and independent model. For use with frontends technologies such as - * htmx where multiple page fragments may be - * rendered in one response. Supported as a return value from Spring WebFlux - * controller methods. + * Public API to render HTML fragments. A fragment is a portion of an HTML page. + * Normally HTML is rendered with a single model and view. This API allows + * using multiple model and view pairs, one for each HTML fragment. * - *

For full page rendering with a single model and view, use {@link Rendering}. + *

For use with frontends technologies such as + * htmx where multiple page fragments may be + * rendered in one response. + * + *

Supported as a return value from annotated controller methods. + * For full page rendering with a single model and view, use {@link Rendering}. * * @author Rossen Stoyanchev * @since 6.2 @@ -63,10 +66,10 @@ public interface FragmentsRendering { /** - * Create a builder and add a fragment with a view name and a 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 model for the request + * Create a builder with one HTML fragment. + * @param viewName the view name for the fragment + * @param model attributes for the fragment, in addition to attributes from the + * shared model for the request * @return this builder */ static Builder with(String viewName, Map model) { @@ -74,8 +77,8 @@ public interface FragmentsRendering { } /** - * Variant of {@link #with(String, Map)} with a view name only, but also - * inheriting model attributes from the shared model for the request. + * Create a builder with one HTML fragment, also inheriting attributes from + * the shared model for the request. * @param viewName the name of the view for the fragment * @return this builder */ @@ -84,8 +87,8 @@ public interface FragmentsRendering { } /** - * Variant of {@link #with(String, Map)} with a collection of fragments. - * @param fragments the fragments to add; each fragment also inherits model + * Create a builder with multiple HTML fragments. + * @param fragments the fragments to add; each fragment also inherits * attributes from the shared model for the request * @return the created builder */ @@ -94,7 +97,7 @@ public interface FragmentsRendering { } /** - * Variant of {@link #with(String, Map)} with a {@link Publisher} of fragments. + * Create a builder 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 @@ -148,25 +151,24 @@ public interface FragmentsRendering { Builder headers(Consumer headersConsumer); /** - * Add a fragment with a view name and a 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 model for the request + * Add an HTML fragment. + * @param viewName the view name for the fragment + * @param model fragment attributes in addition to attributes from the + * shared model for the request * @return this builder */ Builder fragment(String viewName, Map model); /** - * Variant of {@link #fragment(String, Map)} with a view name only, where - * the fragment model also inherits model attributes from the shared + * Add an HTML fragment. The fragment will use attributes from the shared * model for the request. - * @param viewName the name of the view for the fragment + * @param viewName the view name for the fragment * @return this builder */ Builder fragment(String viewName); /** - * Variant of {@link #fragment(String, Map)} with a {@link Fragment}. + * Add an HTML fragment. * @param fragment the fragment to add * @return this builder */ diff --git a/spring-webmvc/src/main/java/org/springframework/web/servlet/view/FragmentsRendering.java b/spring-webmvc/src/main/java/org/springframework/web/servlet/view/FragmentsRendering.java index 8c3257c800..739c20ee84 100644 --- a/spring-webmvc/src/main/java/org/springframework/web/servlet/view/FragmentsRendering.java +++ b/spring-webmvc/src/main/java/org/springframework/web/servlet/view/FragmentsRendering.java @@ -27,11 +27,15 @@ import org.springframework.web.servlet.ModelAndView; import org.springframework.web.servlet.SmartView; /** - * Public API for HTML rendering of a collection of fragments each with a view - * and independent model. For use with frontends technologies such as + * Public API to render HTML fragments. A fragment is a portion of an HTML page. + * Normally HTML is rendered with a single model and view. This API allows + * using multiple model and view pairs, one for each HTML fragment. + * + *

For use with frontends technologies such as * htmx where multiple page fragments may be - * rendered in one response. Supported as a return value from Spring MVC - * controller methods. + * rendered in one response. + * + *

Supported as a return value from controller methods. * * @author Rossen Stoyanchev * @since 6.2 @@ -51,10 +55,10 @@ public interface FragmentsRendering extends SmartView { /** - * Create a builder and add a fragment with a view name and a 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 + * Create a builder with one HTML fragment. + * @param viewName the view name for the fragment + * @param model attributes for the fragment, in addition to attributes from the + * shared model for the request * @return the created builder */ static Builder with(String viewName, Map model) { @@ -62,8 +66,8 @@ public interface FragmentsRendering extends SmartView { } /** - * Variant of {@link #with(String, Map)} with a view name only, but also - * inheriting model attributes from the shared model for the request. + * Create a builder with one HTML fragment, also inheriting attributes from + * the shared model for the request. * @param viewName the name of the view for the fragment * @return the created builder */ @@ -72,8 +76,8 @@ public interface FragmentsRendering extends SmartView { } /** - * Variant of {@link #with(String, Map)} with a collection of fragments. - * @param fragments the fragments to add; each fragment also inherits model + * Create a builder with multiple HTML fragments. + * @param fragments the fragments to add; each fragment also inherits * attributes from the shared model for the request * @return the created builder */ @@ -111,32 +115,32 @@ public interface FragmentsRendering extends SmartView { Builder headers(Consumer headersConsumer); /** - * Add a fragment with a view name and a model. + * Add an HTML fragment. * @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 + * @param model fragment attributes in addition to attributes from the + * shared model for the request * @return this builder */ Builder fragment(String viewName, Map model); /** - * Variant of {@link #fragment(String, Map)} with a view name only, but - * also inheriting model attributes from the shared model for the request. + * Add an HTML fragment. The fragment will use 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); /** - * Variant of {@link #fragment(String, Map)} with a {@link ModelAndView}. - * @param fragment the fragment to add; the fragment also inherits model + * Add an HTML fragment. + * @param fragment the fragment to add; the fragment also inherits * attributes from the shared model for the request * @return this builder */ Builder fragment(ModelAndView fragment); /** - * Variant of {@link #fragment(String, Map)} with a collection of {@link ModelAndView}s. + * Add multiple HTML fragments. * @param fragments the fragments to add; each fragment also inherits model * attributes from the shared model for the request * @return this builder