Edit the core content reference documentation

I edited for the usual stuff: spelling, punctuation,
grammar, formatting, usage, and voice.

Author: Jay Bryant

src/docs/asciidoc/core/core-aop-api.adoc

@@ -1,6 +1,7 @@
 [[beans]]
-= The IoC container
+= The IoC Container
 
+This chapter covers Spring's Inversion of Control (IoC) container.
 
 
 
@@ -143,7 +144,7 @@ The following example shows the basic structure of XML-based configuration metad
 		xsi:schemaLocation="http://www.springframework.org/schema/beans
 			http://www.springframework.org/schema/beans/spring-beans.xsd">
 
-		<bean id="..." class="...">                                       <1> <2>
+		<bean id="..." class="..."> <1> <2>
 			<!-- collaborators and configuration for this bean go here -->
 		</bean>
 
@@ -2136,6 +2137,7 @@ modes:
 
 [[beans-factory-autowiring-modes-tbl]]
 .Autowiring modes
+[cols="20%,80%"]
 |===
 | Mode| Explanation
 
@@ -2568,6 +2570,7 @@ The following table describes the supported scopes:
 
 [[beans-factory-scopes-tbl]]
 .Bean scopes
+[cols="20%,80%"]
 |===
 | Scope| Description
 
@@ -2957,7 +2960,7 @@ understand the "`why`" as well as the "`how`" behind it:
 		<!-- an HTTP Session-scoped bean exposed as a proxy -->
 		<bean id="userPreferences" class="com.something.UserPreferences" scope="session">
 			<!-- instructs the container to proxy the surrounding bean -->
-			<aop:scoped-proxy/>                                                       <1>
+			<aop:scoped-proxy/> <1>
 		</bean>
 
 		<!-- a singleton-scoped bean injected with a proxy to the above bean -->
@@ -4565,7 +4568,7 @@ references and values even when you use the class outside of a container.
 
 
 [[beans-autowired-annotation]]
-=== @Autowired
+=== Using `@Autowired`
 
 NOTE: JSR 330's `@Inject` annotation can be used in place of Spring's `@Autowired` annotation
 in the examples included in this section. See <<beans-standard-annotations,here>> for more details.
@@ -5007,13 +5010,13 @@ The following example shows corresponding bean definitions.
 		<context:annotation-config/>
 
 		<bean class="example.SimpleMovieCatalog">
-			<qualifier value="main"/>                         <1>
+			<qualifier value="main"/> <1>
 
 			<!-- inject any dependencies required by this bean -->
 		</bean>
 
 		<bean class="example.SimpleMovieCatalog">
-			<qualifier value="action"/>                       <2>
+			<qualifier value="action"/> <2>
 
 			<!-- inject any dependencies required by this bean -->
 		</bean>
@@ -5201,7 +5204,7 @@ following example:
 	public class MovieRecommender {
 
 		@Autowired
-		@Offline                               <1>
+		@Offline <1>
 		private MovieCatalog offlineCatalog;
 
 		// ...
@@ -5217,7 +5220,7 @@ Now the bean definition only needs a qualifier `type`, as shown in the following
 [subs="verbatim,quotes"]
 ----
 	<bean class="example.SimpleMovieCatalog">
-		<qualifier type="Offline"/>              <1>
+		<qualifier type="Offline"/> <1>
 		<!-- inject any dependencies required by this bean -->
 	</bean>
 ----
@@ -5459,7 +5462,7 @@ demonstrated in the following example:
 
 		private MovieFinder movieFinder;
 
-		@Resource(name="myMovieFinder")                        <1>
+		@Resource(name="myMovieFinder") <1>
 		public void setMovieFinder(MovieFinder movieFinder) {
 			this.movieFinder = movieFinder;
 		}
@@ -5516,7 +5519,7 @@ named customerPreferenceDao and then falls back to a primary type match for the
 		private CustomerPreferenceDao customerPreferenceDao;
 
 		@Resource
-		private ApplicationContext context;                 <1>
+		private ApplicationContext context; <1>
 
 		public MovieRecommender() {
 		}
@@ -5630,7 +5633,7 @@ annotation. For example, the `@Service` annotation mentioned <<beans-stereotype-
 	@Target(ElementType.TYPE)
 	@Retention(RetentionPolicy.RUNTIME)
 	@Documented
-	@Component                         <1>
+	@Component <1>
 	public @interface Service {
 
 		// ....
@@ -8181,7 +8184,7 @@ the following example shows:
 	public class AppConfig {
 
 		@Bean("dataSource")
-		@Profile("development")                                               <1>
+		@Profile("development") <1>
 		public DataSource standaloneDataSource() {
 			return new EmbeddedDatabaseBuilder()
 				.setType(EmbeddedDatabaseType.HSQL)
@@ -8191,14 +8194,15 @@ the following example shows:
 		}
 
 		@Bean("dataSource")
-		**@Profile("production")**
+		@Profile("production") <2>
 		public DataSource jndiDataSource() throws Exception {
 			Context ctx = new InitialContext();
 			return (DataSource) ctx.lookup("java:comp/env/jdbc/datasource");
 		}
 	}
 ----
 <1> The `standaloneDataSource` method is available only in the `development` profile.
+<2> The `jndiDataSource` method is available only in the `production` profile.
 ====
 
 [NOTE]
@@ -8895,6 +8899,7 @@ The following table describes the standard events that Spring provides:
 
 [[beans-ctx-events-tbl]]
 .Built-in Events
+[cols="30%,70%"]
 |===
 | Event| Explanation
 
@@ -9460,6 +9465,7 @@ The following table lists features provided by the `BeanFactory` and
 
 [[context-introduction-ctx-vs-beanfactory-feature-matrix]]
 .Feature Matrix
+[cols="50%,25%,25%"]
 |===
 | Feature | `BeanFactory` | `ApplicationContext`
 

src/docs/asciidoc/core/core-aop.adoc

@@ -1,111 +1,107 @@
 [[databuffers]]
 = Data Buffers and Codecs
 
-
-
-
-== Introduction
-
 The `DataBuffer` interface defines an abstraction over byte buffers.
-The main reason for introducing it, and not use the standard `java.nio.ByteBuffer` instead, is Netty.
-Netty does not use `ByteBuffer`, but instead offers `ByteBuf` as an alternative.
+The main reason for introducing it (and not using the standard `java.nio.ByteBuffer` instead) is Netty.
+Netty does not use `ByteBuffer` but instead offers `ByteBuf` as an alternative.
 Spring's `DataBuffer` is a simple abstraction over `ByteBuf` that can also be used on non-Netty
-platforms (i.e. Servlet 3.1+).
-
+platforms (that is, Servlet 3.1+).
 
 
 
 == `DataBufferFactory`
 
-The `DataBufferFactory` offers functionality to allocate new data buffers, as well as to wrap
+The `DataBufferFactory` offers functionality to allocate new data buffers as well as to wrap
 existing data.
-The `allocate` methods allocate a new data buffer, with a default or given capacity.
-Though `DataBuffer` implementation grow and shrink on demand, it is more efficient to give the
+The `allocateBuffer` methods allocate a new data buffer with a default or given capacity.
+Though `DataBuffer` implementations grow and shrink on demand, it is more efficient to give the
 capacity upfront, if known.
 The `wrap` methods decorate an existing `ByteBuffer` or byte array.
-Wrapping does not involve allocation: it simply decorates the given data with a `DataBuffer`
+Wrapping does not involve allocation. It decorates the given data with a `DataBuffer`
 implementation.
 
-There are two implementation of `DataBufferFactory`: the `NettyDataBufferFactory` which is meant
-to be used on Netty platforms, such as Reactor Netty.
-The other implementation, the `DefaultDataBufferFactory`, is used on other platforms, such as
-Servlet 3.1+ servers.
-
+There are two implementation of `DataBufferFactory`: the `NettyDataBufferFactory`
+(for Netty platforms, such as Reactor Netty) and
+`DefaultDataBufferFactory` (for other platforms, such as
+Servlet 3.1+ servers).
 
 
 
-== The `DataBuffer` interface
+== The `DataBuffer` Interface
 
-The `DataBuffer` interface is similar to `ByteBuffer`, but offers a number of advantages.
+The `DataBuffer` interface is similar to `ByteBuffer` but offers a number of advantages.
 Similar to Netty's `ByteBuf`, the `DataBuffer` abstraction offers independent read and write
 positions.
-This is different from the JDK's `ByteBuffer`, which only exposes one position for both reading and
-writing, and a separate `flip()` operation to switch between the two  I/O operations.
+This is different from the JDK's `ByteBuffer`, which exposes only one position for both reading and
+writing and a separate `flip()` operation to switch between the two  I/O operations.
 In general, the following invariant holds for the read position, write position, and the capacity:
 
+====
 [literal]
 [subs="verbatim,quotes"]
 --
 	0 <= read position <= write position <= capacity
 --
+====
 
 When reading bytes from the `DataBuffer`, the read position is automatically updated in accordance with
 the amount of data read from the buffer.
 Similarly, when writing bytes to the `DataBuffer`, the write position is updated with the amount of
 data written to the buffer.
-Also, when writing data, the capacity of a `DataBuffer` is automatically expanded, just like `StringBuilder`,
+Also, when writing data, the capacity of a `DataBuffer` is automatically expanded, in the same fashion as `StringBuilder`,
 `ArrayList`, and similar types.
 
 Besides the reading and writing functionality mentioned above, the `DataBuffer` also has methods to
-view a (slice of a) buffer as `ByteBuffer`, `InputStream`, or `OutputStream`.
+view a (slice of a) buffer as a `ByteBuffer`, an `InputStream`, or an `OutputStream`.
 Additionally, it offers methods to determine the index of a given byte.
 
-There are two implementation of `DataBuffer`: the `NettyDataBuffer` which is meant to be used on
-Netty platforms, such as Reactor Netty.
-The other implementation, the `DefaultDataBuffer`, is used on other platforms, such as Servlet 3.1+
-servers.
+As mentioned earlier, there are two implementation of `DataBufferFactory`: the `NettyDataBufferFactory`
+(for Netty platforms, such as Reactor Netty) and
+`DefaultDataBufferFactory` (for other platforms, such as
+Servlet 3.1+ servers).
 
 
 
 === `PooledDataBuffer`
 
 The `PooledDataBuffer` is an extension to `DataBuffer` that adds methods for reference counting.
 The `retain` method increases the reference count by one.
-The `release` method decreases the count by one, and releases the buffer's memory when the count
+The `release` method decreases the count by one and releases the buffer's memory when the count
 reaches 0.
-Both of these methods are related to _reference counting_, a mechanism that is explained below.
+Both of these methods are related to reference counting, a mechanism that we explain <<databuffer-reference-counting,later>>.
 
 Note that `DataBufferUtils` offers useful utility methods for releasing and retaining pooled data
 buffers.
-These methods take a plain `DataBuffer` as parameter, but only call `retain` or `release` if the
+These methods take a plain `DataBuffer` as a parameter but only call `retain` or `release` if the
 passed data buffer is an instance of `PooledDataBuffer`.
 
 
 [[databuffer-reference-counting]]
 ==== Reference Counting
 
-Reference counting is not a common technique in Java; it is much more common in other programming
-languages such as Object C and C++.
-In and of itself, reference counting is not complex: it basically involves tracking the number of
+Reference counting is not a common technique in Java. It is much more common in other programming
+languages, such as Object C and C++.
+In and of itself, reference counting is not complex. It basically involves tracking the number of
 references that apply to an object.
 The reference count of a `PooledDataBuffer` starts at 1, is incremented by calling `retain`,
-and decremented by calling `release`.
-As long as the buffer's reference count is larger than 0 the buffer will not be released.
-When the number decreases to 0, the instance will be released.
-In practice, this means that the reserved memory captured by the buffer will be returned back to
+and is decremented by calling `release`.
+As long as the buffer's reference count is larger than 0, the buffer is not released.
+When the number decreases to 0, the instance is released.
+In practice, this means that the reserved memory captured by the buffer is returned back to
 the memory pool, ready to be used for future allocations.
 
-In general, _the last component to access a `DataBuffer` is responsible for releasing it_.
+In general, the last component to access a `DataBuffer` is responsible for releasing it.
 Within Spring, there are two sorts of components that release buffers: decoders and transports.
-Decoders are responsible for transforming a stream of buffers into other types (see <<codecs>> below),
- and transports are responsible for sending buffers across a network boundary, typically as an HTTP message.
-This means that if you allocate data buffers for the purpose of putting them into an outbound HTTP
-message (i.e. client-side request or server-side response), they do not have to be released.
+Decoders are responsible for transforming a stream of buffers into other types (see <<codecs>>),
+and transports are responsible for sending buffers across a network boundary, typically as an HTTP message.
+This means that, if you allocate data buffers for the purpose of putting them into an outbound HTTP
+message (that is, a client-side request or server-side response), they do not have to be released.
 The other consequence of this rule is that if you allocate data buffers that do not end up in the
-body, for instance because of a thrown exception, you will have to release them yourself.
+body (for instance, because of a thrown exception), you have to release them yourself.
 The following snippet shows a typical `DataBuffer` usage scenario when dealing with methods that
 throw exceptions:
 
+====
 [source,java,indent=0]
 [subs="verbatim,quotes"]
 ----
@@ -130,46 +126,49 @@ throw exceptions:
 
 <1> A new buffer is allocated.
 <2> A boolean flag indicates whether the allocated buffer should be released.
-<3> This example method loads data into the buffer. Note that the method can throw an `IOException`,
-and therefore a `finally` block to release the buffer is required.
-<4> If no exception occurred, we switch the `release` flag to `false` as the buffer will now be
+<3> This example method loads data into the buffer. Note that the method can throw an `IOException`.
+Therefore, a `finally` block to release the buffer is required.
+<4> If no exception occurred, we switch the `release` flag to `false` as the buffer is now
 released as part of sending the HTTP body across the wire.
-<5> If an exception did occur, the flag is still set to `true`, and the buffer will be released
+<5> If an exception did occur, the flag is still set to `true`, and the buffer is released
 here.
+====
 
 
 
-=== DataBufferUtils
+=== `DataBufferUtils`
 
-`DataBufferUtils` contains various utility methods that operate on data buffers.
+The `DataBufferUtils` class contains various utility methods that operate on data buffers.
 It contains methods for reading a `Flux` of `DataBuffer` objects from an `InputStream` or NIO
-`Channel`, and methods for writing a data buffer `Flux` to an `OutputStream` or `Channel`.
+`Channel` and methods for writing a data buffer `Flux` to an `OutputStream` or `Channel`.
 `DataBufferUtils` also exposes `retain` and `release` methods that operate on plain `DataBuffer`
 instances (so that casting to a `PooledDataBuffer` is not required).
 
 Additionally, `DataBufferUtils` exposes `compose`, which merges a stream of data buffers into one.
 For instance, this method can be used to convert the entire HTTP body into a single buffer (and
-from that, a `String`, or `InputStream`).
+from that, a `String` or `InputStream`).
 This is particularly useful when dealing with older, blocking APIs.
 Note, however, that this puts the entire body in memory, and therefore uses more memory than a pure
 streaming solution would.
 
-[codecs]
+
+
+[[codecs]]
 == Codecs
 
 The `org.springframework.core.codec` package contains the two main abstractions for converting a
-stream of bytes into a stream of objects, or vice-versa.
+stream of bytes into a stream of objects or vice-versa.
 The `Encoder` is a strategy interface that encodes a stream of objects into an output stream of
 data buffers.
-The `Decoder` does the reverse: it turns a stream of data buffers into a stream of objects.
-Note that a decoder instance needs to consider <<databuffer-reference-counting, reference counting>>.
+The `Decoder` does the reverse: It turns a stream of data buffers into a stream of objects.
+Note that a decoder instance needs to consider <<databuffer-reference-counting,reference counting>>.
 
-Spring comes with a wide array of default codecs, capable of converting from/to `String`,
-`ByteBuffer`, byte arrays, and also codecs that support marshalling libraries such as JAXB and
+Spring comes with a wide array of default codecs (to convert from and to `String`,
+`ByteBuffer`, and byte arrays) and codecs that support marshalling libraries such as JAXB and
 Jackson (with https://github.com/FasterXML/jackson-core/issues/57[Jackson 2.9+ support for non-blocking parsing]).
 Within the context of Spring WebFlux, codecs are used to convert the request body into a
-`@RequestMapping` parameter, or to convert the return type into the response body that is sent back
+`@RequestMapping` parameter or to convert the return type into the response body that is sent back
 to the client.
-The default codecs are configured in the `WebFluxConfigurationSupport` class, and can easily be
-changed by overriding the `configureHttpMessageCodecs` when inheriting from that class.
-For more information about using codecs in WebFlux, see <<web-reactive#webflux-codecs, this section>>.
+The default codecs are configured in the `WebFluxConfigurationSupport` class. You can
+change them by overriding the `configureHttpMessageCodecs` when you inherit from that class.
+For more information about using codecs in WebFlux, see <<web-reactive#webflux-codecs>>.