DOCSP-49976 Update Documents (mongodb#517)

* DOCSP-49976 Update Documents

* edits

* retrieve ex fixes

* upsert edit

* vale edit

* headings

* input format

* revert output

* edit code example and RR review

* edit

* Edit

* RR review

Author: lindseymoore

snooty.toml

@@ -3,6 +3,7 @@ title = "Go Driver"
 toc_landing_pages = [
     "/connect",
     "/crud",
+    "/crud/update",
     "/monitoring-and-logging",
     "/security",
     "/security/authentication",

source/crud/query/retrieve.txt

@@ -59,79 +59,15 @@ Find Operations
 Use **find operations** to retrieve data from MongoDB. Find operations
 consist of the ``Find()`` and ``FindOne()`` methods.
 
+.. _golang-find-example:
+
 Find All Documents
 ~~~~~~~~~~~~~~~~~~
 
 The ``Find()`` method expects you to pass a ``Context`` type and a
 query filter. The method returns *all* documents that match the filter
 as a ``Cursor`` type.
 
-For an example that uses the ``Find()`` method, see the :ref:`golang-find-example`
-section of this page. To learn how to access data by using a cursor, see
-the :ref:`golang-cursor` guide.
-
-Find One Document
-~~~~~~~~~~~~~~~~~
-
-The ``FindOne()`` method expects you to pass a ``Context`` type and a
-query filter. The method returns *the first document* that matches the
-filter as a ``SingleResult`` type.
-
-For an example that uses the ``FindOne()`` method, see the
-:ref:`golang-find-one-example` section of this page. For an example that
-uses ``FindOne()`` and queries by using a specific ``ObjectId`` value, see
-the :ref:`golang-find-one-by-id` section of this page.
-
-To learn how to access data from a ``SingleResult`` type, see
-:ref:`golang-bson-unmarshalling` in the BSON guide.
-
-.. _golang-retrieve-options:
-
-Modify Behavior
-~~~~~~~~~~~~~~~
-
-You can modify the behavior of ``Find()`` and ``FindOne()`` by passing
-in a ``FindOptions`` and ``FindOneOptions`` type respectively. If you
-don't specify any options, the driver uses the default values for each
-option.
-
-You can configure the commonly used options in both types with the
-following methods:
-
-.. list-table::
-   :widths: 30 70
-   :header-rows: 1
-
-   * - Method
-     - Description
-
-   * - ``SetCollation()`` 
-     - | The type of language collation to use when sorting results.  
-       | Default: ``nil``
-
-   * - ``SetLimit()`` 
-     - | The maximum number of documents to return. 
-       | Default: ``0`` 
-       | This option is not available for ``FindOneOptions``. The
-        ``FindOne()`` method internally uses ``SetLimit(-1)``.
-
-   * - ``SetProjection()`` 
-     - | The fields to include in the returned documents. 
-       | Default: ``nil``
-
-   * - ``SetSkip()`` 
-     - | The number of documents to skip.
-       | Default: ``0``
-
-   * - ``SetSort()`` 
-     - | The field and type of sort to order the matched documents. You can specify an ascending or descending sort.
-       | Default: none
-
-.. _golang-find-example:
-
-Find Example
-````````````
-
 The following example passes a context, filter, and ``FindOptions`` to
 the ``Find()`` method, which performs the following actions:
 
@@ -155,10 +91,16 @@ the ``Find()`` method, which performs the following actions:
       {"item":"Sencha","rating":7,"date_ordered":"2009-11-18T05:00:00Z"}
       {"item":"Masala","rating":8,"date_ordered":"2009-12-01T05:00:00Z"}
 
+To learn how to access data by using a cursor, see the :ref:`golang-cursor` guide.
+
 .. _golang-find-one-example:
 
-Find One Example
-````````````````
+Find One Document
+~~~~~~~~~~~~~~~~~
+
+The ``FindOne()`` method expects you to pass a ``Context`` type and a
+query filter. The method returns *the first document* that matches the
+filter as a ``SingleResult`` type.
 
 The following example passes a context, filter, and ``FindOneOptions``
 to the ``FindOne()`` method, which performs the following actions:
@@ -182,6 +124,13 @@ to the ``FindOne()`` method, which performs the following actions:
 
       {"item":"Masala","rating":9,"date_ordered":"2009-11-12T05:00:00Z"}
 
+For an example that
+uses ``FindOne()`` and queries by using a specific ``ObjectId`` value, see
+the :ref:`golang-find-one-by-id` section of this page.
+
+To learn how to access data from a ``SingleResult`` type, see
+:ref:`golang-bson-unmarshalling` in the BSON guide.
+
 .. _golang-find-one-by-id:
 
 Find One by ObjectId Example
@@ -232,6 +181,48 @@ as parameters to the ``FindOne()`` method to perform the following actions:
    about the ``_id`` field, see the :ref:`_id Field <golang-insert-id>`
    section of the Insert a Document page.
 
+.. _golang-retrieve-options:
+
+Modify Behavior
+~~~~~~~~~~~~~~~
+
+You can modify the behavior of ``Find()`` and ``FindOne()`` by passing
+a ``FindOptions`` or ``FindOneOptions`` instance. If you
+don't specify any options, the driver uses the default values for each
+option.
+
+You can configure the commonly used options in both types with the
+following methods:
+
+.. list-table::
+   :widths: 30 70
+   :header-rows: 1
+
+   * - Method
+     - Description
+
+   * - ``SetCollation()`` 
+     - | The type of language collation to use when sorting results.  
+       | Default: ``nil``
+
+   * - ``SetLimit()`` 
+     - | The maximum number of documents to return. 
+       | Default: ``0`` 
+       | This option is not available for ``FindOneOptions``. The
+        ``FindOne()`` method internally uses ``SetLimit(-1)``.
+
+   * - ``SetProjection()`` 
+     - | The fields to include in the returned documents. 
+       | Default: ``nil``
+
+   * - ``SetSkip()`` 
+     - | The number of documents to skip.
+       | Default: ``0``
+
+   * - ``SetSort()`` 
+     - | The field and type of sort to order the matched documents. You can specify an ascending or descending sort.
+       | Default: none
+
 .. _golang-retrieve-aggregation:
 
 Aggregation Operations