DOCSP-38760: sorts builders (#29)

* DOCSP-38760: sorts builders

* CC change

Author: rustagir

source/builders.txt

@@ -8,16 +8,17 @@ Builders
 
    /builders/filters/
    /builders/projections/
+   /builders/sorts/
 
 The {+driver-short+} provides the following classes that make it easier to use
 the CRUD API:
 
 - :ref:`scala-builders-filters`: Support for building query filters
 - :ref:`scala-builders-projections`: Support for building projections
+- :ref:`scala-builders-sorts`: Support for building sort criteria
 
 .. TODO replace with links
 
-- Sorts: Support for building sort criteria
 - Aggregation: Support for building aggregation pipelines
 - Updates: Support for building updates
 - Indexes: Support for creating index keys

source/builders/sorts.txt

@@ -0,0 +1,95 @@
+.. _scala-builders-sorts:
+
+=====
+Sorts
+=====
+
+.. facet::
+   :name: genre
+   :values: reference
+
+.. meta::
+   :keywords: code example, consistent results, order results
+
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 2
+   :class: singlecol
+
+The ``Sorts`` class provides static factory methods for the MongoDB
+sort criteria operators. Each method returns an instance of the ``Bson``
+type, which can in turn be passed to any method that expects sort
+criteria.
+
+You can import the methods of the ``Sorts``
+class statically, as shown in the following code:
+
+.. code-block:: scala
+
+   import org.mongodb.scala.model.Sorts._
+
+The examples in this guide assume this static import.
+
+Ascending
+---------
+
+To specify an ascending sort, use one of the ``ascending()`` methods.
+
+The following example specifies an ascending sort on the ``quantity``
+field:
+
+.. code-block:: scala
+
+   ascending("quantity")
+
+This example specifies an ascending sort on the ``quantity`` field, followed
+by an ascending sort on the ``totalAmount`` field:
+
+.. code-block:: scala
+
+   ascending("quantity", "totalAmount")
+
+Descending
+----------
+
+To specify a descending sort, use one of the ``descending()`` methods.
+
+This example specifies a descending sort on the ``quantity`` field:
+
+.. code-block:: scala
+
+   descending("quantity")
+
+This example specifies a descending sort on the ``quantity`` field,
+followed by a ``descending`` sort on the ``totalAmount`` field:
+
+.. code-block:: scala
+
+   descending("quantity", "totalAmount") 
+
+Text Score
+----------
+
+To specify a sort on the score of a ``$text`` query, use the
+``metaTextScore()`` method to specify the name of the projected field.
+
+This example specifies a descending sort on the score of a ``$text`` query that will be
+projected into the ``scoreValue`` field:
+
+.. code-block:: scala
+
+   metaTextScore("scoreValue")
+
+Combining Sorts
+---------------
+
+To combine multiple sort criteria, use the ``orderBy()`` method.
+
+This example specifies ascending sorts on the ``quantity`` and
+``totalAmount`` fields, followed by a descending sort on the
+``orderDate`` field:
+
+.. code-block:: scala
+
+   orderBy(ascending("quantity", "totalAmount"), descending("orderDate"))