DATAMONGO-1553 - Polishing.

Convert spaces to tabs. Reorder methods. Add tests, nullability annotations, author tags and slightly rearrange documentation. Migrate tests to AssertJ. Extend year range in license headers.

Original pull request: #519.

src/main/asciidoc/reference/mongodb.adoc

@@ -1914,19 +1914,6 @@ More examples for project operations can be found in the `AggregationTests` clas
 
 MongoDB supports as of Version 3.4 faceted classification using the Aggregation Framework. A faceted classification uses semantic categories, either general or subject-specific, that are combined to create the full classification entry. Documents flowing through the aggregation pipeline are classificated into buckets. A multi-faceted classification enables various aggregations on the same set of input documents, without needing to retrieve the input documents multiple times.
 
-==== SortByCount
-
-SortByCount operations groups incoming documents based on the value of a specified expression, then computes the count of documents in each distinct group. SortVyCount operations require a grouping field or grouping expression. They can be defined via the `sortByCount()` methods of the `Aggregate` class.
-
-.SortByCount operation example
-====
-[source,java]
-----
-// will generate { $sortByCount: "$country" }
-sortByCount("country");
-----
-====
-
 ==== Buckets
 
 Bucket operations categorize incoming documents into groups, called buckets, based on a specified expression and bucket boundaries. Bucket operations require a grouping field or grouping expression. They can be defined via the `bucket()`/`bucketAuto()` methods of the `Aggregate` class. `BucketOperation` and `BucketAutoOperation` can expose accumulations based on aggregation expressions for input documents. The bucket operation can be extended with additional parameters through a fluent API via the `with…()` methods, the `andOutput(String)` method and aliased via the `as(String)` method. Each bucket is represented as a document in the output.
@@ -1992,9 +1979,9 @@ facet(match(Criteria.where("price").exists(true)), bucketAuto("price", 5)).as("c
 facet(match(Criteria.where("country").exists(true)), sortByCount("country")).as("categorizedByCountry"))
 
 // will generate {$facet: {categorizedByYear: [
-//                            { $project: { title: 1, publicationYear: { $year: "publicationDate"}}},
-//                            { $bucketAuto: {groupBy: $price, buckets: 5, output: { titles: {$push:"$title"}}}
-//                         ]}}
+//     { $project: { title: 1, publicationYear: { $year: "publicationDate"}}},
+//     { $bucketAuto: {groupBy: $price, buckets: 5, output: { titles: {$push:"$title"}}}
+// ]}}
 facet(project("title").and("publicationDate").extractYear().as("publicationYear"),
       bucketAuto("publicationYear", 5).andOutput("title").push().as("titles"))
   .as("categorizedByYear"))
@@ -2003,6 +1990,27 @@ facet(project("title").and("publicationDate").extractYear().as("publicationYear"
 
 Note that further details regarding facet operation can be found in the http://docs.mongodb.org/manual/reference/operator/aggregation/facet/[`$facet` section] of the MongoDB Aggregation Framework reference documentation.
 
+[[mongo.aggregation.sort-by-count]]
+==== SortByCount
+
+Sort by count operations group incoming documents based on the value of a specified expression, then compute the count of documents in each distinct group and sort the results by count. It's a handy shortcut to apply sorting for when using <<mongo.aggregation.facet>>. Sort by count operations require a grouping field or grouping expression.
+
+.Sort by count example
+====
+[source,java]
+----
+// will generate { $sortByCount: "$country" }
+sortByCount("country");
+----
+====
+
+A sort by count operation is equivalent to the following BSON:
+
+----
+{ $group: { _id: <expression>, count: { $sum: 1 } } },
+{ $sort: { count: -1 } }
+----
+
 [[mongo.aggregation.projection.expressions]]
 ==== Spring Expression Support in Projection Expressions