DOCSP-32718: add CodeWhisperer comments to collation code snippets

source/code-snippets/collation/aggregation-collation.js

@@ -1,7 +1,13 @@
+/*
+  Retrieve the total number of matching names, grouped by the first_name
+  field and sorted by using the German phonebook collation.
+*/
+// start aggregation collation
 myColl.aggregate(
   [
     { $group: { "_id": "$first_name", "nameCount": { "$sum": 1 } } },
     { $sort: { "_id": 1 } },
   ],
   { collation: { locale: "de@collation=phonebook" } },
 );
+// end aggregation collation

source/code-snippets/collation/collection-auto-collation.js

@@ -0,0 +1,4 @@
+// Retrieve documents that match "photograph" in the "type" field
+// start auto collation
+myColl.find({type: "photograph"});
+// end auto collation

source/code-snippets/collation/collection-collation.js

@@ -1,16 +1,6 @@
-// start create collection with collation
-// Create the collection with a collation
+// Create the "souvenirs" collection and specify the French Canadian collation
+// start collection collation
 db.createCollection("souvenirs", {
   collation: { locale: "fr_CA" },
 });
-// end create collection with collation
-
-// start collection query without collation
-myColl.find({type: "photograph"});
-// end collection query without collation
-
- // start collection query with collation
- myColl.find({type: "photograph"},
-   { collation: { locale: "is", caseFirst: "upper" } }
- );
- // end collection query with collation
+// end collection collation

source/code-snippets/collation/collection-specify-collation.js

@@ -0,0 +1,9 @@
+ /*
+   Retrieve documents that match "photograph" in the "type" field,
+   sorted by the Iceland collation and uppercase precedence.
+*/
+// start specified collation
+ myColl.find({type: "photograph"},
+   { collation: { locale: "is", caseFirst: "upper" } }
+ );
+ // end specified collation

source/code-snippets/collation/find-sort-collation.js

@@ -1,2 +1,8 @@
+/*
+   Retrieve documents that match "New York" in the "city" field,
+   sorted by the "name" field by using the German collation.
+*/
+// start find sort collation
 myColl.find({ city: "New York" }, { collation: { locale: "de" } })
   .sort({ name: 1 });
+// end find sort collation

source/code-snippets/collation/findOneAndDelete-collation.js

@@ -1,10 +1,11 @@
-// start findOneAndDelete example without collation
-await myColl.findOneAndDelete({ a: { $gt: "100" } });
-// end findOneAndDelete example without collation
-
-// start findOneAndDelete example with collation
+/* 
+   Delete the first document that contains a value greater
+   than 100 in the "a" field when ordered by using the
+   English numeric collation order.
+*/
+// start findOneAndDelete collation
 myColl.findOneAndDelete(
   { a: { $gt: "100" } },
   { collation: { locale: "en", numericOrdering: true } },
 );
-// end findOneAndDelete example with collation
+// end findOneAndDelete collation

source/code-snippets/collation/findOneAndDelete-no-collation.js

@@ -0,0 +1,8 @@
+/* 
+   Delete the first document that contains a value greater
+   than 100 in the "a" field when ordered by using the default
+   binary collation order.
+*/
+// start findOneAndDelete no collation
+await myColl.findOneAndDelete({ a: { $gt: "100" } });
+// end findOneAndDelete no collation

source/code-snippets/collation/findOneAndUpdate-collation.js

@@ -1,14 +1,12 @@
-// start findOneAndUpdate without collation
-myColl.findOneAndUpdate(
-  { first_name : { $lt: "Gunter" } },
-  { $set: { verified: true } }
-);
-// end findOneAndUpdate without collation
-
-// start findOneAndUpdate with collation
+/* 
+   Update the "verified" field to "true" for the first document
+   that precedes "Gunter" when ordered by using the
+   German phonebook collation order.
+*/
+// start findOneAndUpdate collation
 myColl.findOneAndUpdate(
   { first_name: { $lt: "Gunter" } },
   { $set: { verified: true } },
   { collation: { locale: "de@collation=phonebook" } },
 );
-// end findOneAndUpdate with collation
+// end findOneAndUpdate collation

source/code-snippets/collation/findOneAndUpdate-default-order-collation.js

@@ -0,0 +1,11 @@
+/*
+   Update the "verified" field to "true" for the first document
+   that precedes "Gunter" when ordered by using the
+   default binary collation order.
+*/
+// start findOneAndUpdate default order collation
+myColl.findOneAndUpdate(
+  { first_name : { $lt: "Gunter" } },
+  { $set: { verified: true } }
+);
+// end findOneAndUpdate default order collation

source/code-snippets/collation/index-collation.js

@@ -1,3 +1,10 @@
+/*
+   Create an index on the "title" field with the "en_US"
+   locale collation, specifying ascending ordering of the
+   "title" field.
+*/
+// start create index collation
 myColl.createIndex(
   { 'title' : 1 },
   { 'collation' : { 'locale' : 'en_US' } });
+// end create index collation

source/code-snippets/collation/query-index-collation.js

@@ -1,14 +1,9 @@
+/*
+   Retrieve documents that match the "year" value "1980"
+   in descending order of the value of the "title" field,
+   specifying a collation that uses the index.
+*/
 // start query index collation
 myColl.find({"year": 1980}, {"collation" : {"locale" : "en_US" }})
   .sort({"title": -1});
-// end query index collation
-
-// start query without index collation
-// no collation specified
-myColl.find({"year": 1980})
-  .sort({"title": -1});
-
-// collation differs from the one on the index
-myColl.find({"year": 1980}, {"collation" : {"locale" : "en_US", "strength": 2 }})
-  .sort({"title": -1});
-// end query without index collation
+// end query index collation

source/code-snippets/collation/query-index-no-collation.js

@@ -0,0 +1,9 @@
+/*
+   Retrieve documents that match the "year" value "1980"
+   in descending order of the value of the "title" field
+   that does not use the collation index.
+*/
+// start index no collation
+myColl.find({"year": 1980})
+  .sort({"title": -1});
+// end index no collation

source/code-snippets/collation/query-not-indexed-collation.js

@@ -0,0 +1,10 @@
+/*
+   Retrieve documents that match the "year" value "1980"
+   in descending order of the value of the "title" field,
+   specifying a collation that does not use the collation
+   index.
+*/
+// start not indexed collation
+myColl.find({"year": 1980}, {"collation" : {"locale" : "en_US", "strength": 2 }})
+  .sort({"title": -1});
+// end not indexed collation

source/fundamentals/collations.txt

@@ -120,26 +120,26 @@ collection.
 
 .. literalinclude:: /code-snippets/collation/collection-collation.js
    :language: javascript
-   :start-after: start create collection with collation
-   :end-before: end create collection with collation
+   :start-after: start collection collation
+   :end-before: end collection collation
 
 Any of the operations that support collations automatically apply the collation
 defined on the collection. The query below searches the ``souvenirs``
 collection and applies the "``fr_CA``" locale collation:
 
-.. literalinclude:: /code-snippets/collation/collection-collation.js
+.. literalinclude:: /code-snippets/collation/collection-auto-collation.js
    :language: javascript
-   :start-after: start collection query without collation
-   :end-before: end collection query without collation
+   :start-after: start auto collation
+   :end-before: end auto collation
 
 You can specify a different collation as a parameter in an operation that
 supports collations. The following query specifies the "``is``" Iceland locale
 and ``caseFirst`` optional parameter with the value "``upper``":
 
-.. literalinclude:: /code-snippets/collation/collection-collation.js
+.. literalinclude:: /code-snippets/collation/collection-specify-collation.js
    :language: javascript
-   :start-after: start collection query with collation
-   :end-before: end collection query with collation
+   :start-after: start specified collation
+   :end-before: end specified collation
 
 Assign a Collation to an Index
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -149,6 +149,8 @@ a collection with a collation set to the "``en_US``" locale.
 
 .. literalinclude:: /code-snippets/collation/index-collation.js
    :language: javascript
+   :start-after: start create index collation
+   :end-before: end create index collation
 
 The following query uses the index we created:
 
@@ -157,14 +159,19 @@ The following query uses the index we created:
    :start-after: start query index collation
    :end-before: end query index collation
 
-The following queries **do not** use the index that we created.  The first
+The following queries **do not** use the index that we created. The first
 query does not include a collation and the second contains a different
 strength value than the collation on the index.
 
-.. literalinclude:: /code-snippets/collation/query-index-collation.js
+.. literalinclude:: /code-snippets/collation/query-not-indexed-collation.js
    :language: javascript
-   :start-after: start query without index collation
-   :end-before: end query without index collation
+   :start-after: start not indexed collation
+   :end-before: end not indexed collation
+
+.. literalinclude:: /code-snippets/collation/query-index-no-collation.js
+   :language: javascript
+   :start-after: start index no collation
+   :end-before: end index no collation
 
 Collation Query Examples
 ~~~~~~~~~~~~~~~~~~~~~~~~
@@ -183,6 +190,8 @@ setting the value of the ``locale`` parameter to ``de``.
 
 .. literalinclude:: /code-snippets/collation/find-sort-collation.js
    :language: javascript
+   :start-after: start find sort collation
+   :end-before: end find sort collation
 
 findOneAndUpdate() Example
 ``````````````````````````
@@ -201,10 +210,10 @@ following documents:
 Consider the following ``findOneAndUpdate()`` operation on this collection
 which **does not** specify a collation:
 
-.. literalinclude:: /code-snippets/collation/findOneAndUpdate-collation.js
+.. literalinclude:: /code-snippets/collation/findOneAndUpdate-default-order-collation.js
    :language: javascript
-   :start-after: start findOneAndUpdate without collation
-   :end-before: end findOneAndUpdate without collation
+   :start-after: start findOneAndUpdate default order collation
+   :end-before: end findOneAndUpdate default order collation
 
 Since "Gunter" is the first sorted result when using a binary collation, none
 of the documents come lexically before and match the ``$lt`` comparison
@@ -220,8 +229,8 @@ umlauts.
 
 .. literalinclude:: /code-snippets/collation/findOneAndUpdate-collation.js
    :language: javascript
-   :start-after: start findOneAndUpdate with collation
-   :end-before: end findOneAndUpdate with collation
+   :start-after: start findOneAndUpdate collation
+   :end-before: end findOneAndUpdate collation 
 
 Since "Günter" lexically comes before "Gunter" using the
 ``de@collation=phonebook`` collation specified in ``findOneAndUpdate()``,
@@ -252,8 +261,8 @@ lexical order.
 
 .. literalinclude:: /code-snippets/collation/findOneAndDelete-collation.js
    :language: javascript
-   :start-after: start findOneAndDelete example with collation
-   :end-before: end findOneAndDelete example with collation
+   :start-after: start findOneAndDelete collation
+   :end-before: end findOneAndDelete collation
 
 After you run the operation above, the collection contains the following
 documents:
@@ -268,10 +277,10 @@ collection of three documents, it matches documents based on the lexical value
 of the strings ("``16``", "``84``", and "``179``"), and deletes the first
 document it finds that matches the query criteria.
 
-.. literalinclude:: /code-snippets/collation/findOneAndDelete-collation.js
+.. literalinclude:: /code-snippets/collation/findOneAndDelete-no-collation.js
    :language: javascript
-   :start-after: start findOneAndDelete example without collation
-   :end-before: end findOneAndDelete example without collation
+   :start-after: start findOneAndDelete no collation
+   :end-before: end findOneAndDelete no collation
 
 Since all the documents contain lexical values in the ``a`` field that
 match the criteria (greater than the lexical value of "``100``"), the operation
@@ -301,3 +310,5 @@ the German phonebook (``de@collation=phonebook`` locale) order.
 
 .. literalinclude:: /code-snippets/collation/aggregation-collation.js
    :language: javascript
+   :start-after: start aggregation collation
+   :end-before: end aggregation collation