docs: Add documentation for enums (#850)

* 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/pubsub_v1/services/publisher/client.py

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

google/pubsub_v1/services/schema_service/client.py

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

google/pubsub_v1/services/subscriber/client.py

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

google/pubsub_v1/types/pubsub.py

@@ -735,7 +735,20 @@ class Subscription(proto.Message):
     """
 
     class State(proto.Enum):
-        r"""Possible states for a subscription."""
+        r"""Possible states for a subscription.
+
+        Values:
+            STATE_UNSPECIFIED (0):
+                Default value. This value is unused.
+            ACTIVE (1):
+                The subscription can actively receive
+                messages
+            RESOURCE_ERROR (2):
+                The subscription cannot receive messages
+                because of an error with the resource to which
+                it pushes messages. See the more detailed error
+                state in the corresponding configuration.
+        """
         STATE_UNSPECIFIED = 0
         ACTIVE = 1
         RESOURCE_ERROR = 2
@@ -1059,7 +1072,24 @@ class BigQueryConfig(proto.Message):
     """
 
     class State(proto.Enum):
-        r"""Possible states for a BigQuery subscription."""
+        r"""Possible states for a BigQuery subscription.
+
+        Values:
+            STATE_UNSPECIFIED (0):
+                Default value. This value is unused.
+            ACTIVE (1):
+                The subscription can actively send messages
+                to BigQuery
+            PERMISSION_DENIED (2):
+                Cannot write to the BigQuery table because of
+                permission denied errors.
+            NOT_FOUND (3):
+                Cannot write to the BigQuery table because it
+                does not exist.
+            SCHEMA_MISMATCH (4):
+                Cannot write to the BigQuery table due to a
+                schema mismatch.
+        """
         STATE_UNSPECIFIED = 0
         ACTIVE = 1
         PERMISSION_DENIED = 2

google/pubsub_v1/types/schema.py

@@ -47,14 +47,35 @@
 class SchemaView(proto.Enum):
     r"""View of Schema object fields to be returned by GetSchema and
     ListSchemas.
+
+    Values:
+        SCHEMA_VIEW_UNSPECIFIED (0):
+            The default / unset value.
+            The API will default to the BASIC view.
+        BASIC (1):
+            Include the name and type of the schema, but
+            not the definition.
+        FULL (2):
+            Include all Schema object fields.
     """
     SCHEMA_VIEW_UNSPECIFIED = 0
     BASIC = 1
     FULL = 2
 
 
 class Encoding(proto.Enum):
-    r"""Possible encoding types for messages."""
+    r"""Possible encoding types for messages.
+
+    Values:
+        ENCODING_UNSPECIFIED (0):
+            Unspecified
+        JSON (1):
+            JSON encoding
+        BINARY (2):
+            Binary encoding, as defined by the schema
+            type. For some schema types, binary encoding may
+            not be available.
+    """
     ENCODING_UNSPECIFIED = 0
     JSON = 1
     BINARY = 2
@@ -82,7 +103,16 @@ class Schema(proto.Message):
     """
 
     class Type(proto.Enum):
-        r"""Possible schema definition types."""
+        r"""Possible schema definition types.
+
+        Values:
+            TYPE_UNSPECIFIED (0):
+                Default value. This value is unused.
+            PROTOCOL_BUFFER (1):
+                A Protocol Buffer schema definition.
+            AVRO (2):
+                An Avro schema definition.
+        """
         TYPE_UNSPECIFIED = 0
         PROTOCOL_BUFFER = 1
         AVRO = 2

samples/generated_samples/snippet_metadata_google.pubsub.v1.json

@@ -8,7 +8,7 @@
     ],
     "language": "PYTHON",
     "name": "google-cloud-pubsub",
-    "version": "2.14.0"
+    "version": "0.1.0"
   },
   "snippets": [
     {