Polish documentation for FrameworkServlet and HttpServletBean

(cherry picked from commit 50c29e64f8)

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

@@ -182,7 +182,7 @@ public abstract class FrameworkServlet extends HttpServletBean implements Applic
 	/** WebApplicationContext implementation class to create. */
 	private Class<?> contextClass = DEFAULT_CONTEXT_CLASS;
 
-	/** WebApplicationContext id to assign. */
+	/** WebApplicationContext ID to assign. */
 	@Nullable
 	private String contextId;
 
@@ -202,29 +202,29 @@ public abstract class FrameworkServlet extends HttpServletBean implements Applic
 	@Nullable
 	private String contextInitializerClasses;
 
-	/** Should we publish the context as a ServletContext attribute?. */
+	/** Whether to publish the context as a ServletContext attribute. */
 	private boolean publishContext = true;
 
-	/** Should we publish a ServletRequestHandledEvent at the end of each request?. */
+	/** Whether to publish a ServletRequestHandledEvent at the end of each request. */
 	private boolean publishEvents = true;
 
-	/** Expose LocaleContext and RequestAttributes as inheritable for child threads?. */
+	/** Whether to expose LocaleContext and RequestAttributes as inheritable for child threads. */
 	private boolean threadContextInheritable = false;
 
-	/** Should we dispatch an HTTP OPTIONS request to {@link #doService}?. */
+	/** Whether to dispatch an HTTP OPTIONS request to {@link #doService}. */
 	private boolean dispatchOptionsRequest = false;
 
-	/** Should we dispatch an HTTP TRACE request to {@link #doService}?. */
+	/** Whether to dispatch an HTTP TRACE request to {@link #doService}. */
 	private boolean dispatchTraceRequest = false;
 
-	/** Whether to log potentially sensitive info (request params at DEBUG + headers at TRACE). */
+	/** Whether to log potentially sensitive info (request params at DEBUG and headers at TRACE). */
 	private boolean enableLoggingRequestDetails = false;
 
 	/** WebApplicationContext for this servlet. */
 	@Nullable
 	private WebApplicationContext webApplicationContext;
 
-	/** If the WebApplicationContext was injected via {@link #setApplicationContext}. */
+	/** Whether the WebApplicationContext was injected via {@link #setApplicationContext}. */
 	private boolean webApplicationContextInjected = false;
 
 	/** Flag used to detect whether onRefresh has already been called. */
@@ -248,7 +248,7 @@ public abstract class FrameworkServlet extends HttpServletBean implements Applic
 	 * such as {@code AnnotationConfigWebApplicationContext}.
 	 * <p>Calling {@link #setContextInitializerClasses} (init-param 'contextInitializerClasses')
 	 * indicates which {@link ApplicationContextInitializer} classes should be used to
-	 * further configure the internal application context prior to refresh().
+	 * further configure the internal application context prior to refresh.
 	 * @see #FrameworkServlet(WebApplicationContext)
 	 */
 	public FrameworkServlet() {
@@ -275,7 +275,7 @@ public abstract class FrameworkServlet extends HttpServletBean implements Applic
 	 * ConfigurableApplicationContext#setParent parent}, the root application context
 	 * will be set as the parent.</li>
 	 * <li>If the given context has not already been assigned an {@linkplain
-	 * ConfigurableApplicationContext#setId id}, one will be assigned to it</li>
+	 * ConfigurableApplicationContext#setId ID}, one will be assigned to it</li>
 	 * <li>{@code ServletContext} and {@code ServletConfig} objects will be delegated to
 	 * the application context</li>
 	 * <li>{@link #postProcessWebApplicationContext} will be called</li>
@@ -337,15 +337,15 @@ public abstract class FrameworkServlet extends HttpServletBean implements Applic
 	}
 
 	/**
-	 * Specify a custom WebApplicationContext id,
-	 * to be used as serialization id for the underlying BeanFactory.
+	 * Specify a custom WebApplicationContext ID,
+	 * to be used as serialization ID for the underlying BeanFactory.
 	 */
 	public void setContextId(@Nullable String contextId) {
 		this.contextId = contextId;
 	}
 
 	/**
-	 * Return the custom WebApplicationContext id, if any.
+	 * Return the custom WebApplicationContext ID, if any.
 	 */
 	@Nullable
 	public String getContextId() {
@@ -472,9 +472,9 @@ public abstract class FrameworkServlet extends HttpServletBean implements Applic
 	 * <p>Default is "false", applying {@link jakarta.servlet.http.HttpServlet}'s
 	 * default behavior (i.e. reflecting the message received back to the client).
 	 * <p>Turn this flag on if you prefer TRACE requests to go through the
-	 * regular dispatching chain, just like other HTTP requests. This usually
-	 * means that your controllers will receive those requests; make sure
-	 * that those endpoints are actually able to handle a TRACE request.
+	 * regular dispatching chain, just like other HTTP requests. This usually means
+	 * that your controllers will receive those requests, in which case you must
+	 * make sure that those endpoints are actually able to handle a TRACE request.
 	 * <p>Note that HttpServlet's default TRACE processing will be applied
 	 * in any case if your controllers happen to not generate a response
 	 * of content type 'message/http' (as required for a TRACE response).
@@ -484,9 +484,9 @@ public abstract class FrameworkServlet extends HttpServletBean implements Applic
 	}
 
 	/**
-	 * Whether to log request params at DEBUG level, and headers at TRACE level.
+	 * Set whether to log request parameters at DEBUG level and headers at TRACE level.
 	 * Both may contain sensitive information.
-	 * <p>By default set to {@code false} so that request details are not shown.
+	 * <p>Defaults to {@code false} so that request details are not shown.
 	 * @param enable whether to enable or not
 	 * @since 5.1
 	 */
@@ -495,7 +495,7 @@ public abstract class FrameworkServlet extends HttpServletBean implements Applic
 	}
 
 	/**
-	 * Whether logging of potentially sensitive, request details at DEBUG and
+	 * Whether logging of potentially sensitive request details at DEBUG and
 	 * TRACE level is allowed.
 	 * @since 5.1
 	 */
@@ -574,7 +574,7 @@ public abstract class FrameworkServlet extends HttpServletBean implements Applic
 			wac = this.webApplicationContext;
 			if (wac instanceof ConfigurableWebApplicationContext cwac && !cwac.isActive()) {
 				// The context has not yet been refreshed -> provide services such as
-				// setting the parent context, setting the application context id, etc
+				// setting the parent context, setting the application context ID, etc
 				if (cwac.getParent() == null) {
 					// The context instance was injected without an explicit parent -> set
 					// the root application context (if any; may be null) as the parent
@@ -587,7 +587,7 @@ public abstract class FrameworkServlet extends HttpServletBean implements Applic
 			// No context instance was injected at construction time -> see if one
 			// has been registered in the servlet context. If one exists, it is assumed
 			// that the parent context (if any) has already been set and that the
-			// user has performed any initialization such as setting the context id
+			// user has performed any initialization such as setting the context ID
 			wac = findWebApplicationContext();
 		}
 		if (wac == null) {
@@ -676,13 +676,13 @@ public abstract class FrameworkServlet extends HttpServletBean implements Applic
 
 	protected void configureAndRefreshWebApplicationContext(ConfigurableWebApplicationContext wac) {
 		if (ObjectUtils.identityToString(wac).equals(wac.getId())) {
-			// The application context id is still set to its original default value
-			// -> assign a more useful id based on available information
+			// The application context ID is still set to its original default value
+			// -> assign a more useful ID based on available information
 			if (this.contextId != null) {
 				wac.setId(this.contextId);
 			}
 			else {
-				// Generate default id...
+				// Generate default ID...
 				wac.setId(ConfigurableWebApplicationContext.APPLICATION_CONTEXT_ID_PREFIX +
 						ObjectUtils.getDisplayString(getServletContext().getContextPath()) + '/' + getServletName());
 			}
@@ -890,7 +890,7 @@ public abstract class FrameworkServlet extends HttpServletBean implements Applic
 	}
 
 	/**
-	 * Delegate GET requests to processRequest/doService.
+	 * Delegate {@code GET} requests to processRequest/doService.
 	 * <p>Will also be invoked by HttpServlet's default implementation of {@code doHead},
 	 * with a {@code NoBodyResponse} that just captures the content length.
 	 * @see #doService
@@ -904,7 +904,7 @@ public abstract class FrameworkServlet extends HttpServletBean implements Applic
 	}
 
 	/**
-	 * Delegate POST requests to {@link #processRequest}.
+	 * Delegate {@code POST} requests to {@link #processRequest}.
 	 * @see #doService
 	 */
 	@Override
@@ -915,7 +915,7 @@ public abstract class FrameworkServlet extends HttpServletBean implements Applic
 	}
 
 	/**
-	 * Delegate PUT requests to {@link #processRequest}.
+	 * Delegate {@code PUT} requests to {@link #processRequest}.
 	 * @see #doService
 	 */
 	@Override
@@ -926,7 +926,7 @@ public abstract class FrameworkServlet extends HttpServletBean implements Applic
 	}
 
 	/**
-	 * Delegate DELETE requests to {@link #processRequest}.
+	 * Delegate {@code DELETE} requests to {@link #processRequest}.
 	 * @see #doService
 	 */
 	@Override
@@ -937,7 +937,7 @@ public abstract class FrameworkServlet extends HttpServletBean implements Applic
 	}
 
 	/**
-	 * Delegate OPTIONS requests to {@link #processRequest}, if desired.
+	 * Delegate {@code OPTIONS} requests to {@link #processRequest}, if desired.
 	 * <p>Applies HttpServlet's standard OPTIONS processing otherwise,
 	 * and also if there is still no 'Allow' header set after dispatching.
 	 * @see #doService
@@ -967,7 +967,7 @@ public abstract class FrameworkServlet extends HttpServletBean implements Applic
 	}
 
 	/**
-	 * Delegate TRACE requests to {@link #processRequest}, if desired.
+	 * Delegate {@code TRACE} requests to {@link #processRequest}, if desired.
 	 * <p>Applies HttpServlet's standard TRACE processing otherwise.
 	 * @see #doService
 	 */
@@ -1171,7 +1171,9 @@ public abstract class FrameworkServlet extends HttpServletBean implements Applic
 
 	/**
 	 * Subclasses must implement this method to do the work of request handling,
-	 * receiving a centralized callback for GET, POST, PUT and DELETE.
+	 * receiving a centralized callback for {@code GET}, {@code POST}, {@code PUT},
+	 * {@code DELETE}, {@code OPTIONS}, and {@code TRACE} requests as well as for
+	 * requests using non-standard HTTP methods (such as WebDAV).
 	 * <p>The contract is essentially the same as that for the commonly overridden
 	 * {@code doGet} or {@code doPost} methods of HttpServlet.
 	 * <p>This class intercepts calls to ensure that exception handling and

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

@@ -55,7 +55,7 @@ import org.springframework.web.context.support.StandardServletEnvironment;
  * parameters is automatic, with the corresponding setter method getting
  * invoked with the converted value. It is also possible for subclasses to
  * specify required properties. Parameters without matching bean property
- * setter will simply be ignored.
+ * setters will simply be ignored.
  *
  * <p>This servlet leaves request handling to subclasses, inheriting the default
  * behavior of HttpServlet ({@code doGet}, {@code doPost}, etc).
@@ -69,7 +69,7 @@ import org.springframework.web.context.support.StandardServletEnvironment;
  *
  * <p>The {@link FrameworkServlet} class is a more specific servlet base
  * class which loads its own application context. FrameworkServlet serves
- * as direct base class of Spring's full-fledged {@link DispatcherServlet}.
+ * as the direct base class of Spring's full-fledged {@link DispatcherServlet}.
  *
  * @author Rod Johnson
  * @author Juergen Hoeller
@@ -107,6 +107,7 @@ public abstract class HttpServletBean extends HttpServlet implements Environment
 	 * Set the {@code Environment} that this servlet runs in.
 	 * <p>Any environment set here overrides the {@link StandardServletEnvironment}
 	 * provided by default.
+	 * @since 3.1
 	 * @throws IllegalArgumentException if environment is not assignable to
 	 * {@code ConfigurableEnvironment}
 	 */
@@ -120,6 +121,7 @@ public abstract class HttpServletBean extends HttpServlet implements Environment
 	 * Return the {@link Environment} associated with this servlet.
 	 * <p>If none specified, a default environment will be initialized via
 	 * {@link #createEnvironment()}.
+	 * @since 3.1
 	 */
 	@Override
 	public ConfigurableEnvironment getEnvironment() {
@@ -133,6 +135,7 @@ public abstract class HttpServletBean extends HttpServlet implements Environment
 	 * Create and return a new {@link StandardServletEnvironment}.
 	 * <p>Subclasses may override this in order to configure the environment or
 	 * specialize the environment type returned.
+	 * @since 3.1
 	 */
 	protected ConfigurableEnvironment createEnvironment() {
 		return new StandardServletEnvironment();