docs: Improve the documentation on Document.fields (#831)

* chore: Add FindNearest API to the preview branch
docs: Improve the documentation on Document.fields

PiperOrigin-RevId: 599602467

Source-Link: googleapis/googleapis@d32bd97

Source-Link: googleapis/googleapis-gen@0545ffc
Copy-Tag: eyJwIjoiLmdpdGh1Yi8uT3dsQm90LnlhbWwiLCJoIjoiMDU0NWZmYzQ4OGI4MmQzYTQ3NzExMThjOTIzZDY0Y2QwYjc1OTk1MyJ9

* 🦉 Updates from OwlBot post-processor

See https://github.com/googleapis/repo-automation-bots/blob/main/packages/owl-bot/README.md

---------

Co-authored-by: Owl Bot <gcf-owl-bot[bot]@users.noreply.github.com>

google/cloud/firestore_v1/types/document.py

@@ -49,28 +49,30 @@ class Document(proto.Message):
 
             The map keys represent field names.
 
-            A simple field name contains only characters ``a`` to ``z``,
-            ``A`` to ``Z``, ``0`` to ``9``, or ``_``, and must not start
-            with ``0`` to ``9``. For example, ``foo_bar_17``.
-
             Field names matching the regular expression ``__.*__`` are
             reserved. Reserved field names are forbidden except in
-            certain documented contexts. The map keys, represented as
+            certain documented contexts. The field names, represented as
             UTF-8, must not exceed 1,500 bytes and cannot be empty.
 
             Field paths may be used in other contexts to refer to
             structured fields defined here. For ``map_value``, the field
-            path is represented by the simple or quoted field names of
-            the containing fields, delimited by ``.``. For example, the
+            path is represented by a dot-delimited (``.``) string of
+            segments. Each segment is either a simple field name
+            (defined below) or a quoted field name. For example, the
             structured field
             ``"foo" : { map_value: { "x&y" : { string_value: "hello" }}}``
-            would be represented by the field path ``foo.x&y``.
+            would be represented by the field path
+            :literal:`foo.`x&y\``.
+
+            A simple field name contains only characters ``a`` to ``z``,
+            ``A`` to ``Z``, ``0`` to ``9``, or ``_``, and must not start
+            with ``0`` to ``9``. For example, ``foo_bar_17``.
 
-            Within a field path, a quoted field name starts and ends
-            with :literal:`\`` and may contain any character. Some
-            characters, including :literal:`\``, must be escaped using a
-            ``\``. For example, :literal:`\`x&y\`` represents ``x&y``
-            and :literal:`\`bak\`tik\`` represents :literal:`bak`tik`.
+            A quoted field name starts and ends with :literal:`\`` and
+            may contain any character. Some characters, including
+            :literal:`\``, must be escaped using a ``\``. For example,
+            :literal:`\`x&y\`` represents ``x&y`` and
+            :literal:`\`bak\`tik\`` represents :literal:`bak`tik`.
         create_time (google.protobuf.timestamp_pb2.Timestamp):
             Output only. The time at which the document was created.
 

google/cloud/firestore_v1/types/query.py

@@ -36,6 +36,15 @@
 class StructuredQuery(proto.Message):
     r"""A Firestore query.
 
+    The query stages are executed in the following order:
+
+    1. from
+    2. where
+    3. select
+    4. order_by + start_at + end_at
+    5. offset
+    6. limit
+
     Attributes:
         select (google.cloud.firestore_v1.types.StructuredQuery.Projection):
             Optional sub-set of the fields to return.