Editing pass for new content in reference documentation.

Closes: #4049

Author: Jay Bryant

src/main/asciidoc/reference/mongo-property-converters.adoc

@@ -1,11 +1,11 @@
 [[mongo.property-converters]]
 == Property Converters - Mapping specific fields
 
-While <<mongo.custom-converters, type-based conversion>> already offers ways to influence the conversion and representation of certain types within the target store it has its limitations when only certain values or properties of a particular type should be considered for conversion.
-Property-based converters allow configuring conversion rules on a per-property basis, either declarative, via `@ValueConverter`, or programmatic by registering a `PropertyValueConverter` for a specific property.
+While <<mongo.custom-converters, type-based conversion>> already offers ways to influence the conversion and representation of certain types within the target store, it has limitations when only certain values or properties of a particular type should be considered for conversion.
+Property-based converters allow configuring conversion rules on a per-property basis, either declaratively (via `@ValueConverter`) or programmatically (by registering a `PropertyValueConverter` for a specific property).
 
-A `PropertyValueConverter` can transform a given value into its store representation (**write**) and back (**read**) as shown in the snippet below.
-The additional `ValueConversionContext` provides additional information, such as mapping metadata and direct `read`/`write` methods.
+A `PropertyValueConverter` can transform a given value into its store representation (write) and back (read) as the following listing shows.
+The additional `ValueConversionContext` provides additional information, such as mapping metadata and direct `read` and `write` methods.
 
 .A simple PropertyValueConverter
 ====
@@ -26,18 +26,18 @@ class ReversingValueConverter implements PropertyValueConverter<String, String,
 ----
 ====
 
-`PropertyValueConverter` instances can be obtained via `CustomConversions#getPropertyValueConverter(…)` delegating to `PropertyValueConversions`, typically using a `PropertyValueConverterFactory` providing the actual converter.
-Depending on the applications needs, multiple instances of `PropertyValueConverterFactory` can be chained or decorated, for example to apply caching.
-By default, a caching implementation is used that is capable of serving types with a default constructor or enum values.
-A set of predefined factories is available through `PropertyValueConverterFactory` factory methods.
-Use `PropertyValueConverterFactory.beanFactoryAware(…)` to obtain a `PropertyValueConverter` instances from an `ApplicationContext`.
+You can obtain `PropertyValueConverter` instances from `CustomConversions#getPropertyValueConverter(…)` by delegating to `PropertyValueConversions`, typically by using a `PropertyValueConverterFactory` to provide the actual converter.
+Depending on your application's needs, you can chain or decorate multiple instances of `PropertyValueConverterFactory` -- for example, to apply caching.
+By default, Spring Data MongoDB uses a caching implementation that can serve types with a default constructor or enum values.
+A set of predefined factories is available through the factory methods in `PropertyValueConverterFactory`.
+You can use `PropertyValueConverterFactory.beanFactoryAware(…)` to obtain a `PropertyValueConverter` instance from an `ApplicationContext`.
 
 You can change the default behavior through `ConverterConfiguration`.
 
 [[mongo.property-converters.declarative]]
 === Declarative Value Converter
 
-The most straight forward usage of a `PropertyValueConverter` is by annotating properties with the `@ValueConverter` annotation that defines the converter type.
+The most straight forward usage of a `PropertyValueConverter` is by annotating properties with the `@ValueConverter` annotation that defines the converter type:
 
 .Declarative PropertyValueConverter
 ====
@@ -54,8 +54,8 @@ class Person {
 [[mongo.property-converters.programmatic]]
 === Programmatic Value Converter Registration
 
-Programmatic registration registers `PropertyValueConverter` instances for properties within an entity model using a `PropertyValueConverterRegistrar` as shown below.
-The difference to declarative registration is that programmatic registration happens entirely outside of the entity model.
+Programmatic registration registers `PropertyValueConverter` instances for properties within an entity model by using a `PropertyValueConverterRegistrar`, as the following example shows.
+The difference between declarative registration and programmatic registration is that programmatic registration happens entirely outside of the entity model.
 Such an approach is useful if you cannot or do not want to annotate the entity model.
 
 .Programmatic PropertyValueConverter registration
@@ -76,25 +76,22 @@ registrar.registerConverter(Person.class, Person::getSsn())
 <2> Type safe variant that allows to register a converter and its conversion functions.
 ====
 
-[WARNING]
-====
-Dot-notation (such as `registerConverter(Person.class, "address.street", …)`) nagivating across properties into subdocuments is *not* supported when registering converters.
-====
+WARNING: Dot notation (such as `registerConverter(Person.class, "address.street", …)`) for nagivating across properties into subdocuments is *not* supported when registering converters.
 
 [[mongo.property-converters.value-conversions]]
 === MongoDB property value conversions
 
-The above sections outlined the purpose an overall structure of `PropertyValueConverters`.
-This section will focus on MongoDB specific aspects.
+The preceding sections outlined the purpose an overall structure of `PropertyValueConverters`.
+This section focuses on MongoDB specific aspects.
 
 ==== MongoValueConverter and MongoConversionContext
 
-`MongoValueConverter` offers a pre typed `PropertyValueConverter` interface leveraging the `MongoConversionContext`.
+`MongoValueConverter` offers a pre-typed `PropertyValueConverter` interface that uses `MongoConversionContext`.
 
 ==== MongoCustomConversions configuration
 
-`MongoCustomConversions` are by default capable of handling declarative value converters depending on the configured `PropertyValueConverterFactory`.
-`MongoConverterConfigurationAdapter` is there to help set up programmatic value conversions or define the `PropertyValueConverterFactory` to be used.
+By default, `MongoCustomConversions` can handle declarative value converters, depending on the configured `PropertyValueConverterFactory`.
+`MongoConverterConfigurationAdapter` helps to set up programmatic value conversions or define the `PropertyValueConverterFactory` to be used.
 
 .Configuration Sample
 ====

src/main/asciidoc/reference/mongo-repositories.adoc

@@ -2,8 +2,6 @@
 = MongoDB Repositories
 
 [[mongo-repo-intro]]
-== Introduction
-
 This chapter points out the specialties for repository support for MongoDB. This chapter builds on the core repository support explained in <<repositories>>. You should have a sound understanding of the basic concepts explained there.
 
 [[mongo-repo-usage]]
@@ -292,13 +290,13 @@ NOTE: If the property criterion compares a document, the order of the fields and
 [[mongodb.repositories.queries.update]]
 === Repository Update Methods
 
-The keywords in the preceding table can also be used to create queries that identify matching documents for running updates on them.
-The actual update action is defined via the `@Update` annotation on the method itself as shown in the snippet below. +
-Please note that the naming schema for derived queries starts with `find`.
-Using _update_ (as in `updateAllByLastname(...)`) is only allowed in combination with `@Query`.
+You can also use the keywords in the preceding table to create queries that identify matching documents for running updates on them.
+The actual update action is defined by the `@Update` annotation on the method itself, as the following listing shows.
+Note that the naming schema for derived queries starts with `find`.
+Using `update` (as in `updateAllByLastname(...)`) is allowed only in combination with `@Query`.
 
-The update is applied to *all* matching documents and it is *not* possible to limit the scope by passing in a `Page` nor using any of the <<repositories.limit-query-result,limiting keywords>>. +
-The return type can be either `void` or a _numeric_ type, such as `long` which holds the number of modified documents.
+The update is applied to *all* matching documents and it is *not* possible to limit the scope by passing in a `Page` or by using any of the <<repositories.limit-query-result,limiting keywords>>.
+The return type can be either `void` or a _numeric_ type, such as `long`, to hold the number of modified documents.
 
 .Update Methods
 ====
@@ -326,18 +324,15 @@ public interface PersonRepository extends CrudRepository<Person, String> {
   void updateAllByLastname(String lastname, int increment); <6>
 }
 ----
-<1> The filter query for the update is derived from the method name. The update is as is and does not bind any parameters.
-<2> The actual increment value is defined by the _increment_ method argument that is bound to the `?1` placeholder.
-<3> It is possible to use SpEL for parameter binding.
+<1> The filter query for the update is derived from the method name. The update is "`as is`" and does not bind any parameters.
+<2> The actual increment value is defined by the `increment` method argument that is bound to the `?1` placeholder.
+<3> Use the Spring Expression Language (SpEL) for parameter binding.
 <4> Use the `pipeline` attribute to issue <<mongo-template.aggregation-update,aggregation pipeline updates>>.
 <5> The update may contain complex objects.
 <6> Combine a <<mongodb.repositories.queries.json-based,string based query>> with an update.
 ====
 
-[WARNING]
-====
-Repository updates do not emit persistence nor mapping lifecycle events.
-====
+WARNING: Repository updates do not emit persistence nor mapping lifecycle events.
 
 [[mongodb.repositories.queries.delete]]
 === Repository Delete Queries