Polish ref docs

- stop referring to Java Config as new
- stop referring to Struts 2.x as if it were new
- polish AOT documentation
- etc.

Author: sbrannen

framework-docs/src/docs/asciidoc/core/core-aot.adoc

@@ -5,7 +5,7 @@ This chapter covers Spring's Ahead of Time (AOT) optimizations.
 
 For AOT support specific to integration tests, see <<testing.adoc#testcontext-aot, Ahead of Time Support for Tests>>.
 
-[[aot-introduction]]
+[[core.aot.introduction]]
 == Introduction to Ahead of Time Optimizations
 
 Spring's support for AOT optimizations is meant to inspect an `ApplicationContext` at build time and apply decisions and discovery logic that usually happens at runtime.
@@ -263,30 +263,29 @@ The following example registers `Account` for serialization.
 [[core.aot.hints.testing]]
 === Testing Runtime Hints
 
-Spring Core also ships `RuntimeHintsPredicates`, an utility for checking that existing hints match a particular use case.
-This can be used in your own tests, for validating that a `RuntimeHintsRegistrar` has the expected result.
-We can write a test for our `SpellCheckService` and ensure that we can load a dictionary at runtime:
+Spring Core also ships `RuntimeHintsPredicates`, a utility for checking that existing hints match a particular use case.
+This can be used in your own tests to validate that a `RuntimeHintsRegistrar` contains the expected results.
+We can write a test for our `SpellCheckService` and ensure that we will be able to load a dictionary at runtime:
 
 include::code:SpellCheckServiceTests[tag=hintspredicates]
 
-With `RuntimeHintsPredicates`, we can check for reflection, resource, serialization or proxy generation hints.
+With `RuntimeHintsPredicates`, we can check for reflection, resource, serialization, or proxy generation hints.
 This approach works well for unit tests but implies that the runtime behavior of a component is well known.
 
 You can learn more about the global runtime behavior of an application by running its test suite (or the app itself) with the {docs-graalvm}/native-image/metadata/AutomaticMetadataCollection/[GraalVM tracing agent].
 This agent will record all relevant calls requiring GraalVM hints at runtime and write them out as JSON configuration files.
 
 For more targeted discovery and testing, Spring Framework ships a dedicated module with core AOT testing utilities, `"org.springframework:spring-core-test"`.
-This module contains the RuntimeHints Agent, a Java agent that all method invocations that are related to runtime hints and helps you to assert that a given `RuntimeHints` instance covers all recorded invocations.
-Let's consider a piece of infrastructure for which we'd like to test the hints we're contributing during the AOT phase.
-
+This module contains the RuntimeHints Agent, a Java agent that records all method invocations that are related to runtime hints and helps you to assert that a given `RuntimeHints` instance covers all recorded invocations.
+Let's consider a piece of infrastructure for which we'd like to test the hints we're contributing during the AOT processing phase.
 
 include::code:SampleReflection[]
 
-We can then write a Java test (no native compilation required!) that checks our contributed hints:
+We can then write a unit test (no native compilation required) that checks our contributed hints:
 
 include::code:SampleReflectionRuntimeHintsTests[]
 
-If you forgot to contribute a hint, the test will fail and give some details on the invocation:
+If you forgot to contribute a hint, the test will fail and provide some details about the invocation:
 
 [source,txt,indent=0,subs="verbatim,quotes"]
 ----
@@ -303,6 +302,6 @@ io.spring.runtimehintstesting.SampleReflection#performReflection, Line 19
 io.spring.runtimehintstesting.SampleReflectionRuntimeHintsTests#lambda$shouldRegisterReflectionHints$0, Line 25
 ----
 
-There are various ways to configure this Java agent into your build, please refer to your build tool and test execution plugin documentation.
-The agent itself can be configured to instrument some packages (by default, only `org.springframework` is instrumented).
-You'll find more details in the https://github.com/spring-projects/spring-framework/blob/main/buildSrc/README.md[Spring Framework buildSrc README].
+There are various ways to configure this Java agent in your build, so please refer to the documentation of your build tool and test execution plugin.
+The agent itself can be configured to instrument specific packages (by default, only `org.springframework` is instrumented).
+You'll find more details in the {spring-framework-main-code}/buildSrc/README.md[Spring Framework `buildSrc` README] file.

framework-docs/src/docs/asciidoc/core/core-beans.adoc

@@ -107,12 +107,10 @@ configuration metadata is actually written. These days, many developers choose
 
 For information about using other forms of metadata with the Spring container, see:
 
-* <<beans-annotation-config,Annotation-based configuration>>: Spring 2.5 introduced
-  support for annotation-based configuration metadata.
-* <<beans-java, Java-based configuration>>: Starting with Spring 3.0, many features
-  provided by the Spring JavaConfig project became part of the core Spring Framework.
-  Thus, you can define beans external to your application classes by using Java rather
-  than XML files. To use these new features, see the
+* <<beans-annotation-config,Annotation-based configuration>>: define beans using
+  annotation-based configuration metadata.
+* <<beans-java, Java-based configuration>>: define beans external to your application
+  classes by using Java rather than XML files. To use these features, see the
   {api-spring-framework}/context/annotation/Configuration.html[`@Configuration`],
   {api-spring-framework}/context/annotation/Bean.html[`@Bean`],
   {api-spring-framework}/context/annotation/Import.html[`@Import`],
@@ -124,14 +122,12 @@ beans as `<bean/>` elements inside a top-level `<beans/>` element. Java
 configuration typically uses `@Bean`-annotated methods within a `@Configuration` class.
 
 These bean definitions correspond to the actual objects that make up your application.
-Typically, you define service layer objects, data access objects (DAOs), presentation
-objects such as Struts `Action` instances, infrastructure objects such as Hibernate
-`SessionFactories`, JMS `Queues`, and so forth. Typically, one does not configure
-fine-grained domain objects in the container, because it is usually the responsibility
-of DAOs and business logic to create and load domain objects. However, you can use
-Spring's integration with AspectJ to configure objects that have been created outside
-the control of an IoC container. See <<aop-atconfigurable,Using AspectJ to
-dependency-inject domain objects with Spring>>.
+Typically, you define service layer objects, persistence layer objects such as
+repositories or data access objects (DAOs), presentation objects such as Web controllers,
+infrastructure objects such as a JPA `EntityManagerFactory`, JMS queues, and so forth.
+Typically, one does not configure fine-grained domain objects in the container, because
+it is usually the responsibility of repositories and business logic to create and load
+domain objects.
 
 The following example shows the basic structure of XML-based configuration metadata:
 
@@ -157,12 +153,11 @@ The following example shows the basic structure of XML-based configuration metad
 ----
 
 <1> The `id` attribute is a string that identifies the individual bean definition.
-
 <2> The `class` attribute defines the type of the bean and uses the fully qualified
-classname.
+class name.
 
-The value of the `id` attribute refers to collaborating objects. The XML for
-referring to collaborating objects is not shown in this example. See
+The value of the `id` attribute can be used to refer to collaborating objects. The XML
+for referring to collaborating objects is not shown in this example. See
 <<beans-dependencies,Dependencies>> for more information.
 
 
@@ -2839,7 +2834,7 @@ processed by the Spring `DispatcherServlet`, no special setup is necessary.
 `DispatcherServlet` already exposes all relevant state.
 
 If you use a Servlet web container, with requests processed outside of Spring's
-`DispatcherServlet` (for example, when using JSF or Struts), you need to register the
+`DispatcherServlet` (for example, when using JSF), you need to register the
 `org.springframework.web.context.request.RequestContextListener` `ServletRequestListener`.
 This can be done programmatically by using the `WebApplicationInitializer` interface.
 Alternatively, add the following declaration to your web application's `web.xml` file:
@@ -7515,7 +7510,7 @@ container. It includes the following topics:
 [[beans-java-basic-concepts]]
 === Basic Concepts: `@Bean` and `@Configuration`
 
-The central artifacts in Spring's new Java-configuration support are
+The central artifacts in Spring's Java configuration support are
 `@Configuration`-annotated classes and `@Bean`-annotated methods.
 
 The `@Bean` annotation is used to indicate that a method instantiates, configures, and

framework-docs/src/docs/asciidoc/web/integration.adoc

@@ -23,21 +23,21 @@ first take a look at common Spring configuration that is not specific to any one
 framework. (This section is equally applicable to Spring's own web framework variants.)
 
 One of the concepts (for want of a better word) espoused by Spring's lightweight
-application model is that of a layered architecture. Remember that in a "`classic`"
+application model is that of a layered architecture. Remember that in a "classic"
 layered architecture, the web layer is but one of many layers. It serves as one of the
 entry points into a server-side application, and it delegates to service objects
 (facades) that are defined in a service layer to satisfy business-specific (and
 presentation-technology agnostic) use cases. In Spring, these service objects, any other
-business-specific objects, data-access objects, and others exist in a distinct "`business
-context`", which contains no web or presentation layer objects (presentation objects,
-such as Spring MVC controllers, are typically configured in a distinct "`presentation
-context`"). This section details how you can configure a Spring container (a
+business-specific objects, data-access objects, and others exist in a distinct "business
+context", which contains no web or presentation layer objects (presentation objects,
+such as Spring MVC controllers, are typically configured in a distinct "presentation
+context"). This section details how you can configure a Spring container (a
 `WebApplicationContext`) that contains all of the 'business beans' in your application.
 
 Moving on to specifics, all you need to do is declare a
 {api-spring-framework}/web/context/ContextLoaderListener.html[`ContextLoaderListener`]
 in the standard Jakarta EE servlet `web.xml` file of your web application and add a
-`contextConfigLocation`<context-param/> section (in the same file) that defines which
+`contextConfigLocation` `<context-param/>` section (in the same file) that defines which
 set of Spring XML configuration files to load.
 
 Consider the following `<listener/>` configuration:
@@ -67,7 +67,7 @@ object based on the bean definitions and stores it in the `ServletContext` of th
 application.
 
 All Java web frameworks are built on top of the Servlet API, so you can use the
-following code snippet to get access to this "`business context`" `ApplicationContext`
+following code snippet to get access to this "business context" `ApplicationContext`
 created by the `ContextLoaderListener`.
 
 The following example shows how to get the `WebApplicationContext`:
@@ -119,7 +119,7 @@ The key element in Spring's JSF integration is the JSF `ELResolver` mechanism.
 
 `SpringBeanFacesELResolver` is a JSF compliant `ELResolver` implementation,
 integrating with the standard Unified EL as used by JSF and JSP. It delegates to
-Spring's "`business context`" `WebApplicationContext` first and then to the
+Spring's "business context" `WebApplicationContext` first and then to the
 default resolver of the underlying JSF implementation.
 
 Configuration-wise, you can define `SpringBeanFacesELResolver` in your JSF
@@ -157,27 +157,26 @@ The following example shows how to use `FacesContextUtils`:
 
 
 [[struts]]
-== Apache Struts 2.x
+== Apache Struts
 
 Invented by Craig McClanahan, https://struts.apache.org[Struts] is an open-source project
-hosted by the Apache Software Foundation. At the time, it greatly simplified the
+hosted by the Apache Software Foundation. Struts 1.x greatly simplified the
 JSP/Servlet programming paradigm and won over many developers who were using proprietary
-frameworks. It simplified the programming model, it was open source (and thus free as in
-beer), and it had a large community, which let the project grow and become popular among
-Java web developers.
+frameworks. It simplified the programming model; it was open source; and it had a large
+community, which let the project grow and become popular among Java web developers.
 
-As a successor to the original Struts 1.x, check out Struts 2.x and the Struts-provided
-https://struts.apache.org/release/2.3.x/docs/spring-plugin.html[Spring Plugin] for the
-built-in Spring integration.
+As a successor to the original Struts 1.x, check out Struts 2.x or more recent versions
+as well as the Struts-provided
+https://struts.apache.org/plugins/spring/[Spring Plugin] for built-in Spring integration.
 
 
 
 
 [[tapestry]]
-== Apache Tapestry 5.x
+== Apache Tapestry
 
-https://tapestry.apache.org/[Tapestry] is a ""Component oriented framework for creating
-dynamic, robust, highly scalable web applications in Java.""
+https://tapestry.apache.org/[Tapestry] is a "Component oriented framework for creating
+dynamic, robust, highly scalable web applications in Java."
 
 While Spring has its own <<mvc, powerful web layer>>, there are a number of unique
 advantages to building an enterprise Java application by using a combination of Tapestry
@@ -195,6 +194,6 @@ https://tapestry.apache.org/integrating-with-spring-framework.html[integration m
 The following links go to further resources about the various web frameworks described in
 this chapter.
 
-* The https://www.oracle.com/technetwork/java/javaee/javaserverfaces-139869.html[JSF] homepage
+* The https://www.oracle.com/java/technologies/javaserverfaces.html[JSF] homepage
 * The https://struts.apache.org/[Struts] homepage
 * The https://tapestry.apache.org/[Tapestry] homepage

framework-docs/src/main/java/org/springframework/docs/core/aot/hints/testing/SampleReflection.java

@@ -38,4 +38,5 @@ public void performReflection() {
 			logger.error("reflection failed", exc);
 		}
 	}
-}
+
+}

framework-docs/src/main/java/org/springframework/docs/core/aot/hints/testing/SampleReflectionRuntimeHintsTests.java

@@ -29,8 +29,9 @@
 
 import static org.assertj.core.api.Assertions.assertThat;
 
-// This annotation conditions the execution of tests only if the agent is loaded in the current JVM
-// it also tags tests with the "RuntimeHints" JUnit tag
+// @EnabledIfRuntimeHintsAgent signals that the annotated test class or test
+// method is only enabled if the RuntimeHintsAgent is loaded on the current JVM.
+// It also tags tests with the "RuntimeHints" JUnit tag.
 @EnabledIfRuntimeHintsAgent
 class SampleReflectionRuntimeHintsTests {
 

framework-docs/src/main/java/org/springframework/docs/core/aot/hints/testing/SpellCheckServiceTests.java

@@ -44,4 +44,5 @@ public void registerHints(RuntimeHints hints, ClassLoader classLoader) {
 			hints.resources().registerPattern("dicts/*");
 		}
 	}
+
 }

framework-docs/src/main/java/org/springframework/docs/core/aot/refresh/AotProcessingSample.java

@@ -38,15 +38,13 @@ public void createAotContext() {
 	@ComponentScan
 	@Import({DataSourceConfiguration.class, ContainerConfiguration.class})
 	public class MyApplication {
-
 	}
 	// end::myapplication[]
 
 	class DataSourceConfiguration {
-
 	}
 
 	class ContainerConfiguration {
-
 	}
+
 }