docs: Add documentation for enums (#709)

* 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>

Author: gcf-owl-bot[bot]

google/cloud/logging_v2/services/config_service_v2/client.py

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

google/cloud/logging_v2/services/logging_service_v2/client.py

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

google/cloud/logging_v2/services/metrics_service_v2/client.py

@@ -1029,7 +1029,7 @@ def sample_delete_log_metric():
             metadata=metadata,
         )
 
-    def __enter__(self):
+    def __enter__(self) -> "MetricsServiceV2Client":
         return self
 
     def __exit__(self, type, value, traceback):

google/cloud/logging_v2/types/logging.py

@@ -557,7 +557,20 @@ class SuppressionInfo(proto.Message):
         """
 
         class Reason(proto.Enum):
-            r"""An indicator of why entries were omitted."""
+            r"""An indicator of why entries were omitted.
+
+            Values:
+                REASON_UNSPECIFIED (0):
+                    Unexpected default.
+                RATE_LIMIT (1):
+                    Indicates suppression occurred due to relevant entries being
+                    received in excess of rate limits. For quotas and limits,
+                    see `Logging API quotas and
+                    limits <https://cloud.google.com/logging/quotas#api-limits>`__.
+                NOT_CONSUMED (2):
+                    Indicates suppression occurred due to the
+                    client not consuming responses quickly enough.
+            """
             REASON_UNSPECIFIED = 0
             RATE_LIMIT = 1
             NOT_CONSUMED = 2

google/cloud/logging_v2/types/logging_config.py

@@ -70,7 +70,19 @@
 
 
 class LifecycleState(proto.Enum):
-    r"""LogBucket lifecycle states."""
+    r"""LogBucket lifecycle states.
+
+    Values:
+        LIFECYCLE_STATE_UNSPECIFIED (0):
+            Unspecified state. This is only used/useful
+            for distinguishing unset values.
+        ACTIVE (1):
+            The normal and active state.
+        DELETE_REQUESTED (2):
+            The resource has been marked for deletion by
+            the user. For some resources (e.g. buckets),
+            this can be reversed by an un-delete operation.
+    """
     LIFECYCLE_STATE_UNSPECIFIED = 0
     ACTIVE = 1
     DELETE_REQUESTED = 2
@@ -83,6 +95,22 @@ class OperationState(proto.Enum):
     is created, the current state of the operation can be queried
     even before the operation is finished and the final result is
     available.
+
+    Values:
+        OPERATION_STATE_UNSPECIFIED (0):
+            Should not be used.
+        OPERATION_STATE_SCHEDULED (1):
+            The operation is scheduled.
+        OPERATION_STATE_WAITING_FOR_PERMISSIONS (2):
+            Waiting for necessary permissions.
+        OPERATION_STATE_RUNNING (3):
+            The operation is running.
+        OPERATION_STATE_SUCCEEDED (4):
+            The operation was completed successfully.
+        OPERATION_STATE_FAILED (5):
+            The operation failed.
+        OPERATION_STATE_CANCELLED (6):
+            The operation was cancelled by the user.
     """
     OPERATION_STATE_UNSPECIFIED = 0
     OPERATION_STATE_SCHEDULED = 1
@@ -371,7 +399,17 @@ class LogSink(proto.Message):
     """
 
     class VersionFormat(proto.Enum):
-        r"""Deprecated. This is unused."""
+        r"""Deprecated. This is unused.
+
+        Values:
+            VERSION_FORMAT_UNSPECIFIED (0):
+                An unspecified format version that will
+                default to V2.
+            V2 (1):
+                ``LogEntry`` version 2 format.
+            V1 (2):
+                ``LogEntry`` version 1 format.
+        """
         VERSION_FORMAT_UNSPECIFIED = 0
         V2 = 1
         V1 = 2

google/cloud/logging_v2/types/logging_metrics.py

@@ -168,7 +168,14 @@ class LogMetric(proto.Message):
     """
 
     class ApiVersion(proto.Enum):
-        r"""Logging API version."""
+        r"""Logging API version.
+
+        Values:
+            V2 (0):
+                Logging API v2.
+            V1 (1):
+                Logging API v1.
+        """
         V2 = 0
         V1 = 1