docs: clarify semantics of 'merge' argument to 'Document.set'

docs/batch.rst

@@ -1,6 +1,14 @@
 Batches
 ~~~~~~~
 
+.. automodule:: google.cloud.firestore_v1.base_batch
+  :members:
+  :show-inheritance:
+
 .. automodule:: google.cloud.firestore_v1.batch
   :members:
   :show-inheritance:
+
+.. automodule:: google.cloud.firestore_v1.async_batch
+  :members:
+  :show-inheritance:

docs/client.rst

@@ -1,6 +1,14 @@
 Client
 ~~~~~~
 
+.. automodule:: google.cloud.firestore_v1.base_client
+  :members:
+  :show-inheritance:
+
 .. automodule:: google.cloud.firestore_v1.client
   :members:
   :show-inheritance:
+
+.. automodule:: google.cloud.firestore_v1.async_client
+  :members:
+  :show-inheritance:

docs/collection.rst

@@ -1,6 +1,14 @@
 Collections
 ~~~~~~~~~~~
 
+.. automodule:: google.cloud.firestore_v1.base_collection
+  :members:
+  :show-inheritance:
+
 .. automodule:: google.cloud.firestore_v1.collection
   :members:
   :show-inheritance:
+
+.. automodule:: google.cloud.firestore_v1.async_collection
+  :members:
+  :show-inheritance:

docs/document.rst

@@ -1,6 +1,14 @@
 Documents
 ~~~~~~~~~
 
+.. automodule:: google.cloud.firestore_v1.base_document
+  :members:
+  :show-inheritance:
+
 .. automodule:: google.cloud.firestore_v1.document
   :members:
   :show-inheritance:
+
+.. automodule:: google.cloud.firestore_v1.async_document
+  :members:
+  :show-inheritance:

docs/query.rst

@@ -1,6 +1,14 @@
 Queries
 ~~~~~~~
 
+.. automodule:: google.cloud.firestore_v1.base_query
+  :members:
+  :show-inheritance:
+
 .. automodule:: google.cloud.firestore_v1.query
   :members:
   :show-inheritance:
+
+.. automodule:: google.cloud.firestore_v1.async_query
+  :members:
+  :show-inheritance:

docs/transaction.rst

@@ -1,7 +1,17 @@
 Transactions
 ~~~~~~~~~~~~
 
+.. automodule:: google.cloud.firestore_v1.base_transaction
+  :inherited-members:
+  :members:
+  :show-inheritance:
+
 .. automodule:: google.cloud.firestore_v1.transaction
   :inherited-members:
   :members:
   :show-inheritance:
+
+.. automodule:: google.cloud.firestore_v1.async_transaction
+  :inherited-members:
+  :members:
+  :show-inheritance:

google/cloud/firestore_v1/base_collection.py

@@ -288,12 +288,15 @@ def limit(self, count: int) -> BaseQuery:
 
     def limit_to_last(self, count: int):
         """Create a limited to last query with this collection as parent.
+
         .. note::
            `limit` and `limit_to_last` are mutually exclusive.
            Setting `limit_to_last` will drop previously set `limit`.
+
         See
         :meth:`~google.cloud.firestore_v1.query.Query.limit_to_last`
         for more information on this method.
+
         Args:
             count (int): Maximum number of documents to return that
                 match the query.

google/cloud/firestore_v1/base_query.py

@@ -370,9 +370,11 @@ def limit(self, count: int) -> "BaseQuery":
         """Limit a query to return at most `count` matching results.
 
         If the current query already has a `limit` set, this will override it.
+
         .. note::
            `limit` and `limit_to_last` are mutually exclusive.
            Setting `limit` will drop previously set `limit_to_last`.
+
         Args:
             count (int): Maximum number of documents to return that match
                 the query.
@@ -398,9 +400,11 @@ def limit_to_last(self, count: int) -> "BaseQuery":
         """Limit a query to return the last `count` matching results.
         If the current query already has a `limit_to_last`
         set, this will override it.
+
         .. note::
            `limit` and `limit_to_last` are mutually exclusive.
            Setting `limit_to_last` will drop previously set `limit`.
+
         Args:
             count (int): Maximum number of documents to return that match
                 the query.

google/cloud/firestore_v1/document.py

@@ -65,7 +65,14 @@ def create(
         retry: retries.Retry = gapic_v1.method.DEFAULT,
         timeout: float = None,
     ) -> write.WriteResult:
-        """Create the current document in the Firestore database.
+        """Create a document in the Firestore database.
+
+        >>> document_data = {"a": 1, "b": {"c": "Two"}}
+        >>> document.get().to_dict() is None  # does not exist
+        True
+        >>> document.create(document_data)
+        >>> document.get().to_dict() == document_data  # exists
+        True
 
         Args:
             document_data (dict): Property names and values to use for
@@ -95,23 +102,51 @@ def set(
         retry: retries.Retry = gapic_v1.method.DEFAULT,
         timeout: float = None,
     ) -> write.WriteResult:
-        """Replace the current document in the Firestore database.
+        """Create / replace / merge a document in the Firestore database.
+
+        - To "upsert" a document (create if it doesn't exist, replace completely
+          if it does), leave the ``merge`` argument at its default:
+
+          >>> document_data = {"a": 1, "b": {"c": "Two"}}
+          >>> document.get().to_dict() is None  # document exists
+          False
+          >>> document.set(document_data)
+          >>> document.get().to_dict() == document_data  # exists
+          True
+
+        - To "merge" ``document_data`` with an existing document (creating if
+          the document dos not exist), pass ``merge`` as True``:
+
+          >>> document_data = {"a": 1, "b": {"c": "Two"}}
+          >>> document.get().to_dict() == {"d": "Three", "b": {}} # exists
+          >>> document.set(document_data, merge=True)
+          >>> document.get().to_dict() == {"a": 1, "d": "Three", "b": {"c": "Two"}}
+          True
+
+          In this case, existing documents with top-level keys which are
+          not present in ``document_data`` (``"d"``) will preserve the values
+          of those keys.
+
+
+        - To merge only specific fields of ``document_data`` with existing
+          documents (creating if the document does not exist), pass ``merge``
+          as a list of field paths:
+
 
-        A write ``option`` can be specified to indicate preconditions of
-        the "set" operation. If no ``option`` is specified and this document
-        doesn't exist yet, this method will create it.
+          >>> document_data = {"a": 1, "b": {"c": "Two"}}
+          >>> document.get().to_dict() == {"b": {"c": "One", "d": "Four" }} # exists
+          True
+          >>> document.set(document_data, merge=["b.c"])
+          >>> document.get().to_dict() == {"b": {"c": "Two", "d": "Four" }}
+          True
 
-        Overwrites all content for the document with the fields in
-        ``document_data``. This method performs almost the same functionality
-        as :meth:`create`. The only difference is that this method doesn't
-        make any requirements on the existence of the document (unless
-        ``option`` is used), whereas as :meth:`create` will fail if the
-        document already exists.
+          For more information on field paths, see
+          :meth:`~google.cloud.firestore_v1.base_client.BaseClient.field_path`.
 
         Args:
             document_data (dict): Property names and values to use for
                 replacing a document.
-            merge (Optional[bool] or Optional[List<apispec>]):
+            merge (Optional[bool] or Optional[List<fieldpath>]):
                 If True, apply merging instead of overwriting the state
                 of the document.
             retry (google.api_core.retry.Retry): Designation of what errors, if any,
@@ -142,9 +177,9 @@ def update(
         override these preconditions.
 
         Each key in ``field_updates`` can either be a field name or a
-        **field path** (For more information on **field paths**, see
-        :meth:`~google.cloud.firestore_v1.client.Client.field_path`.) To
-        illustrate this, consider a document with
+        **field path** (For more information on field paths, see
+        :meth:`~google.cloud.firestore_v1.base_client.BaseClient.field_path`.)
+        To illustrate this, consider a document with
 
         .. code-block:: python