Polishing.

Reorder methods. Tweak Javadoc and documentation wording. Mention projection expressions in the what's new section. Reformat code.

See #3583
Original pull request: #3585.

src/main/asciidoc/new-features.adoc

@@ -5,6 +5,7 @@
 == What's New in Spring Data MongoDB 3.2
 
 * Support for <<embedded-entities,Embedded Types>> to unwrap nested objects into the parent `Document`.
+* <<mongo-template.querying.field-selection,Support expressions to define field projections>>.
 
 [[new-features.3.1]]
 == What's New in Spring Data MongoDB 3.1

src/main/asciidoc/reference/mongodb.adoc

@@ -1251,7 +1251,7 @@ The `Query` class has some additional methods that provide options for the query
 ==== Selecting fields
 
 MongoDB supports https://docs.mongodb.com/manual/tutorial/project-fields-from-query-results/[projecting fields] returned by a query.
-A projection can in- & exclude fields (the `_id` field is always included unless explicitly excluded) based on their name.
+A projection can include and exclude fields (the `_id` field is always included unless explicitly excluded) based on their name.
 
 .Selecting result fields
 ====
@@ -1268,13 +1268,13 @@ public class Person {
     Address address;
 }
 
-query.fields().include("lastname"); <1>
+query.fields().include("lastname");              <1>
 
 query.fields().exclude("id").include("lastname") <2>
 
-query.fields().include("address") <3>
+query.fields().include("address")                <3>
 
-query.fields().include("address.city") <4>
+query.fields().include("address.city")           <4>
 
 
 ----
@@ -1284,31 +1284,31 @@ query.fields().include("address.city") <4>
 <4> Result will contain the `_id` and and `address` object that only contains the `city` field via `{ "address.city" : 1 }`.
 ====
 
-Starting with MongoDB 4.4 it is possible to use the aggregation expressions syntax for field projections as shown below.
+Starting with MongoDB 4.4 you can use aggregation expressions for field projections as shown below:
 
-.Computing result fields with expressions
+.Computing result fields using expressions
 ====
 [source,java]
 ----
 query.fields()
-  .project(MongoExpression.create("'$toUpper' : '$last_name'")) <1>
-  .as("last_name"); <2>
+  .project(MongoExpression.create("'$toUpper' : '$last_name'"))         <1>
+  .as("last_name");                                                     <2>
 
 query.fields()
-  .project(StringOperators.valueOf("lastname").toUpper()) <3>
+  .project(StringOperators.valueOf("lastname").toUpper())               <3>
   .as("last_name");
 
 query.fields()
   .project(AggregationSpELExpression.expressionOf("toUpper(lastname)")) <4>
   .as("last_name");
 ----
-<1> Use a native expression. The used field names must refer to the ones of the document within the database.
-<2> Assign the field name that shall hold the expression result in the target document. The resulting field name will never be mapped against the domain model.
+<1> Use a native expression. The used field name must refer to field names within the database document.
+<2> Assign the field name to which the expression result is projected. The resulting field name is not mapped against the domain model.
 <3> Use an `AggregationExpression`. Other than native `MongoExpression`, field names are mapped to the ones used in the domain model.
 <4> Use SpEL along with an `AggregationExpression` to invoke expression functions. Field names are mapped to the ones used in the domain model.
 ====
 
-`@Query(fields='...')` allows usage of expression field projections at `Repository` level as described in <<mongodb.repositories.queries.json-based>>.
+`@Query(fields="…")` allows usage of expression field projections at `Repository` level as described in <<mongodb.repositories.queries.json-based>>.
 
 [[mongo-template.querying]]
 === Methods for Querying for Documents