docs: Add documentation for enums (#679)

* docs: Add documentation for enums

fix: Add context manager return types

chore: Update gapic-generator-python to v1.8.1
PiperOrigin-RevId: 503210727

Source-Link: googleapis/googleapis@a391fd1

Source-Link: googleapis/googleapis-gen@0080f83
Copy-Tag: eyJwIjoiLmdpdGh1Yi8uT3dsQm90LnlhbWwiLCJoIjoiMDA4MGY4MzBkZWMzN2MzMzg0MTU3MDgyYmNlMjc5ZTM3MDc5ZWE1OCJ9

* 🦉 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_admin_v1/services/firestore_admin/client.py

@@ -1945,7 +1945,7 @@ def sample_update_database():
         # Done; return the response.
         return response
 
-    def __enter__(self):
+    def __enter__(self) -> "FirestoreAdminClient":
         return self
 
     def __exit__(self, type, value, traceback):

google/cloud/firestore_admin_v1/types/database.py

@@ -74,20 +74,65 @@ class DatabaseType(proto.Enum):
         for information about how to choose.
 
         Mode changes are only allowed if the database is empty.
+
+        Values:
+            DATABASE_TYPE_UNSPECIFIED (0):
+                The default value. This value is used if the
+                database type is omitted.
+            FIRESTORE_NATIVE (1):
+                Firestore Native Mode
+            DATASTORE_MODE (2):
+                Firestore in Datastore Mode.
         """
         DATABASE_TYPE_UNSPECIFIED = 0
         FIRESTORE_NATIVE = 1
         DATASTORE_MODE = 2
 
     class ConcurrencyMode(proto.Enum):
-        r"""The type of concurrency control mode for transactions."""
+        r"""The type of concurrency control mode for transactions.
+
+        Values:
+            CONCURRENCY_MODE_UNSPECIFIED (0):
+                Not used.
+            OPTIMISTIC (1):
+                Use optimistic concurrency control by
+                default. This mode is available for Cloud
+                Firestore databases.
+            PESSIMISTIC (2):
+                Use pessimistic concurrency control by
+                default. This mode is available for Cloud
+                Firestore databases.
+                This is the default setting for Cloud Firestore.
+            OPTIMISTIC_WITH_ENTITY_GROUPS (3):
+                Use optimistic concurrency control with
+                entity groups by default.
+                This is the only available mode for Cloud
+                Datastore.
+                This mode is also available for Cloud Firestore
+                with Datastore Mode but is not recommended.
+        """
         CONCURRENCY_MODE_UNSPECIFIED = 0
         OPTIMISTIC = 1
         PESSIMISTIC = 2
         OPTIMISTIC_WITH_ENTITY_GROUPS = 3
 
     class AppEngineIntegrationMode(proto.Enum):
-        r"""The type of App Engine integration mode."""
+        r"""The type of App Engine integration mode.
+
+        Values:
+            APP_ENGINE_INTEGRATION_MODE_UNSPECIFIED (0):
+                Not used.
+            ENABLED (1):
+                If an App Engine application exists in the
+                same region as this database, App Engine
+                configuration will impact this database. This
+                includes disabling of the application &
+                database, as well as disabling writes to the
+                database.
+            DISABLED (2):
+                Appengine has no affect on the ability of
+                this database to serve requests.
+        """
         APP_ENGINE_INTEGRATION_MODE_UNSPECIFIED = 0
         ENABLED = 1
         DISABLED = 2

google/cloud/firestore_admin_v1/types/field.py

@@ -129,7 +129,28 @@ class TtlConfig(proto.Message):
         """
 
         class State(proto.Enum):
-            r"""The state of applying the TTL configuration to all documents."""
+            r"""The state of applying the TTL configuration to all documents.
+
+            Values:
+                STATE_UNSPECIFIED (0):
+                    The state is unspecified or unknown.
+                CREATING (1):
+                    The TTL is being applied. There is an active
+                    long-running operation to track the change.
+                    Newly written documents will have TTLs applied
+                    as requested. Requested TTLs on existing
+                    documents are still being processed. When TTLs
+                    on all existing documents have been processed,
+                    the state will move to 'ACTIVE'.
+                ACTIVE (2):
+                    The TTL is active for all documents.
+                NEEDS_REPAIR (3):
+                    The TTL configuration could not be enabled for all existing
+                    documents. Newly written documents will continue to have
+                    their TTL applied. The LRO returned when last attempting to
+                    enable TTL for this ``Field`` has failed, and may have more
+                    details.
+            """
             STATE_UNSPECIFIED = 0
             CREATING = 1
             ACTIVE = 2

google/cloud/firestore_admin_v1/types/index.py

@@ -69,6 +69,22 @@ class Index(proto.Message):
     class QueryScope(proto.Enum):
         r"""Query Scope defines the scope at which a query is run. This is
         specified on a StructuredQuery's ``from`` field.
+
+        Values:
+            QUERY_SCOPE_UNSPECIFIED (0):
+                The query scope is unspecified. Not a valid
+                option.
+            COLLECTION (1):
+                Indexes with a collection query scope
+                specified allow queries against a collection
+                that is the child of a specific document,
+                specified at query time, and that has the
+                collection id specified by the index.
+            COLLECTION_GROUP (2):
+                Indexes with a collection group query scope
+                specified allow queries against all collections
+                that has the collection id specified by the
+                index.
         """
         QUERY_SCOPE_UNSPECIFIED = 0
         COLLECTION = 1
@@ -80,6 +96,31 @@ class State(proto.Enum):
         will transition to the ``READY`` state. If the index creation
         encounters a problem, the index will transition to the
         ``NEEDS_REPAIR`` state.
+
+        Values:
+            STATE_UNSPECIFIED (0):
+                The state is unspecified.
+            CREATING (1):
+                The index is being created.
+                There is an active long-running operation for
+                the index. The index is updated when writing a
+                document. Some index data may exist.
+            READY (2):
+                The index is ready to be used.
+                The index is updated when writing a document.
+                The index is fully populated from all stored
+                documents it applies to.
+            NEEDS_REPAIR (3):
+                The index was being created, but something
+                went wrong. There is no active long-running
+                operation for the index, and the most recently
+                finished long-running operation failed. The
+                index is not updated when writing a document.
+                Some index data may exist.
+                Use the google.longrunning.Operations API to
+                determine why the operation that last attempted
+                to create this index failed, then re-create the
+                index.
         """
         STATE_UNSPECIFIED = 0
         CREATING = 1
@@ -115,13 +156,33 @@ class IndexField(proto.Message):
         """
 
         class Order(proto.Enum):
-            r"""The supported orderings."""
+            r"""The supported orderings.
+
+            Values:
+                ORDER_UNSPECIFIED (0):
+                    The ordering is unspecified. Not a valid
+                    option.
+                ASCENDING (1):
+                    The field is ordered by ascending field
+                    value.
+                DESCENDING (2):
+                    The field is ordered by descending field
+                    value.
+            """
             ORDER_UNSPECIFIED = 0
             ASCENDING = 1
             DESCENDING = 2
 
         class ArrayConfig(proto.Enum):
-            r"""The supported array value configurations."""
+            r"""The supported array value configurations.
+
+            Values:
+                ARRAY_CONFIG_UNSPECIFIED (0):
+                    The index does not support additional array
+                    queries.
+                CONTAINS (1):
+                    The index supports array containment queries.
+            """
             ARRAY_CONFIG_UNSPECIFIED = 0
             CONTAINS = 1
 

google/cloud/firestore_admin_v1/types/operation.py

@@ -36,7 +36,33 @@
 
 
 class OperationState(proto.Enum):
-    r"""Describes the state of the operation."""
+    r"""Describes the state of the operation.
+
+    Values:
+        OPERATION_STATE_UNSPECIFIED (0):
+            Unspecified.
+        INITIALIZING (1):
+            Request is being prepared for processing.
+        PROCESSING (2):
+            Request is actively being processed.
+        CANCELLING (3):
+            Request is in the process of being cancelled
+            after user called
+            google.longrunning.Operations.CancelOperation on
+            the operation.
+        FINALIZING (4):
+            Request has been processed and is in its
+            finalization stage.
+        SUCCESSFUL (5):
+            Request has completed successfully.
+        FAILED (6):
+            Request has finished being processed, but
+            encountered an error.
+        CANCELLED (7):
+            Request has finished being cancelled after
+            user called
+            google.longrunning.Operations.CancelOperation.
+    """
     OPERATION_STATE_UNSPECIFIED = 0
     INITIALIZING = 1
     PROCESSING = 2
@@ -145,7 +171,16 @@ class IndexConfigDelta(proto.Message):
         """
 
         class ChangeType(proto.Enum):
-            r"""Specifies how the index is changing."""
+            r"""Specifies how the index is changing.
+
+            Values:
+                CHANGE_TYPE_UNSPECIFIED (0):
+                    The type of change is not specified or known.
+                ADD (1):
+                    The single field index is being added.
+                REMOVE (2):
+                    The single field index is being removed.
+            """
             CHANGE_TYPE_UNSPECIFIED = 0
             ADD = 1
             REMOVE = 2
@@ -171,7 +206,16 @@ class TtlConfigDelta(proto.Message):
         """
 
         class ChangeType(proto.Enum):
-            r"""Specifies how the TTL config is changing."""
+            r"""Specifies how the TTL config is changing.
+
+            Values:
+                CHANGE_TYPE_UNSPECIFIED (0):
+                    The type of change is not specified or known.
+                ADD (1):
+                    The TTL config is being added.
+                REMOVE (2):
+                    The TTL config is being removed.
+            """
             CHANGE_TYPE_UNSPECIFIED = 0
             ADD = 1
             REMOVE = 2

google/cloud/firestore_bundle/types/bundle.py

@@ -53,6 +53,12 @@ class BundledQuery(proto.Message):
     class LimitType(proto.Enum):
         r"""If the query is a limit query, should the limit be applied to
         the beginning or the end of results.
+
+        Values:
+            FIRST (0):
+
+            LAST (1):
+
         """
         FIRST = 0
         LAST = 1

google/cloud/firestore_v1/services/firestore/client.py

@@ -1986,7 +1986,7 @@ def sample_create_document():
         # Done; return the response.
         return response
 
-    def __enter__(self):
+    def __enter__(self) -> "FirestoreClient":
         return self
 
     def __exit__(self, type, value, traceback):

google/cloud/firestore_v1/types/firestore.py

@@ -1421,7 +1421,34 @@ class TargetChange(proto.Message):
     """
 
     class TargetChangeType(proto.Enum):
-        r"""The type of change."""
+        r"""The type of change.
+
+        Values:
+            NO_CHANGE (0):
+                No change has occurred. Used only to send an updated
+                ``resume_token``.
+            ADD (1):
+                The targets have been added.
+            REMOVE (2):
+                The targets have been removed.
+            CURRENT (3):
+                The targets reflect all changes committed before the targets
+                were added to the stream.
+
+                This will be sent after or with a ``read_time`` that is
+                greater than or equal to the time at which the targets were
+                added.
+
+                Listeners can wait for this change if read-after-write
+                semantics are desired.
+            RESET (4):
+                The targets have been reset, and a new initial state for the
+                targets will be returned in subsequent changes.
+
+                After the initial state is complete, ``CURRENT`` will be
+                returned even if the target was previously indicated to be
+                ``CURRENT``.
+        """
         NO_CHANGE = 0
         ADD = 1
         REMOVE = 2