Polishing ProblemDetail support

See gh-28665

spring-web/src/main/java/org/springframework/http/ProblemDetail.java

@@ -23,8 +23,11 @@ import org.springframework.util.Assert;
 
 /**
  * Representation of an RFC 7807 problem detail, including all RFC-defined
- * fields. For an extended response with more fields, create a subclass that
- * exposes the additional fields.
+ * properties.
+ *
+ * <p>For an extended response, create a subclass with additional properties.
+ * A subclass can use the {@link ProblemDetail#ProblemDetail(ProblemDetail)}
+ * copy constructor to extend an existing {@code ProblemDetail} instance.
  *
  * @author Rossen Stoyanchev
  * @since 6.0
@@ -63,8 +66,8 @@ public class ProblemDetail {
 	}
 
 	/**
-	 * Copy constructor that could be used from a subclass to re-create a
-	 * {@code ProblemDetail} in order to extend it with more fields.
+	 * Copy constructor that a subclass can use to re-create and extend a
+	 * {@code ProblemDetail} with additional properties.
 	 */
 	protected ProblemDetail(ProblemDetail other) {
 		this.type = other.type;
@@ -75,7 +78,7 @@ public class ProblemDetail {
 	}
 
 	/**
-	 * For deserialization.
+	 * No-arg constructor, for deserialization.
 	 */
 	protected ProblemDetail() {
 	}

spring-web/src/main/java/org/springframework/http/ResponseEntity.java

@@ -264,10 +264,11 @@ public class ResponseEntity<T> extends HttpEntity<T> {
 
 	/**
 	 * Create a builder for a {@code ResponseEntity} with the given
-	 * {@link ProblemDetail} as the body, also matching to its
-	 * {@link ProblemDetail#getStatus() status}. An {@code @ExceptionHandler}
-	 * method can use to add response headers, or otherwise it can return
-	 * {@code ProblemDetail}.
+	 * {@link ProblemDetail} as the body, and its
+	 * {@link ProblemDetail#getStatus() status} as the status.
+	 * <p>Note that {@code ProblemDetail} is supported as a return value from
+	 * controller methods and from {@code @ExceptionHandler} methods. The method
+	 * here is convenient to also add response headers.
 	 * @param body the details for an HTTP error response
 	 * @return the created builder
 	 * @since 6.0

spring-web/src/main/java/org/springframework/web/ErrorResponseException.java

@@ -32,7 +32,7 @@ import org.springframework.lang.Nullable;
  * <p>The exception can be used as is, or it can be extended as a more specific
  * exception that populates the {@link ProblemDetail#setType(URI) type} or
  * {@link ProblemDetail#setDetail(String) detail} fields, or potentially adds
- * other non-standard fields.
+ * other non-standard properties.
  *
  * @author Rossen Stoyanchev
  * @since 6.0