docs: Add documentation for enums (#291)

* 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: https://github.com/googleapis/googleapis-gen/commit/0080f830dec37c3384157082bce279e37079ea58
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/trace_v1/services/trace_service/client.py

@@ -766,7 +766,7 @@ def sample_patch_traces():
             metadata=metadata,
         )
 
-    def __enter__(self):
+    def __enter__(self) -> "TraceServiceClient":
         return self
 
     def __exit__(self, type, value, traceback):

google/cloud/trace_v1/types/trace.py

@@ -157,6 +157,18 @@ class TraceSpan(proto.Message):
     class SpanKind(proto.Enum):
         r"""Type of span. Can be used to specify additional relationships
         between spans in addition to a parent/child relationship.
+
+        Values:
+            SPAN_KIND_UNSPECIFIED (0):
+                Unspecified.
+            RPC_SERVER (1):
+                Indicates that the span covers server-side
+                handling of an RPC or other remote network
+                request.
+            RPC_CLIENT (2):
+                Indicates that the span covers the
+                client-side wrapper around an RPC or other
+                remote request.
         """
         SPAN_KIND_UNSPECIFIED = 0
         RPC_SERVER = 1
@@ -276,7 +288,24 @@ class ListTracesRequest(proto.Message):
     """
 
     class ViewType(proto.Enum):
-        r"""Type of data returned for traces in the list."""
+        r"""Type of data returned for traces in the list.
+
+        Values:
+            VIEW_TYPE_UNSPECIFIED (0):
+                Default is ``MINIMAL`` if unspecified.
+            MINIMAL (1):
+                Minimal view of the trace record that
+                contains only the project and trace IDs.
+            ROOTSPAN (2):
+                Root span view of the trace record that
+                returns the root spans along with the minimal
+                trace data.
+            COMPLETE (3):
+                Complete view of the trace record that contains the actual
+                trace data. This is equivalent to calling the REST ``get``
+                or RPC ``GetTrace`` method using the ID of each listed
+                trace.
+        """
         VIEW_TYPE_UNSPECIFIED = 0
         MINIMAL = 1
         ROOTSPAN = 2

google/cloud/trace_v2/services/trace_service/client.py

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

google/cloud/trace_v2/types/trace.py

@@ -121,6 +121,36 @@ class Span(proto.Message):
     class SpanKind(proto.Enum):
         r"""Type of span. Can be used to specify additional relationships
         between spans in addition to a parent/child relationship.
+
+        Values:
+            SPAN_KIND_UNSPECIFIED (0):
+                Unspecified. Do NOT use as default.
+                Implementations MAY assume SpanKind.INTERNAL to
+                be default.
+            INTERNAL (1):
+                Indicates that the span is used internally.
+                Default value.
+            SERVER (2):
+                Indicates that the span covers server-side
+                handling of an RPC or other remote network
+                request.
+            CLIENT (3):
+                Indicates that the span covers the
+                client-side wrapper around an RPC or other
+                remote request.
+            PRODUCER (4):
+                Indicates that the span describes producer
+                sending a message to a broker. Unlike client and
+                server, there is no direct critical path latency
+                relationship between producer and consumer spans
+                (e.g. publishing a message to a pubsub service).
+            CONSUMER (5):
+                Indicates that the span describes consumer
+                receiving a message from a broker. Unlike client
+                and  server, there is no direct critical path
+                latency relationship between producer and
+                consumer spans (e.g. receiving a message from a
+                pubsub service subscription).
         """
         SPAN_KIND_UNSPECIFIED = 0
         INTERNAL = 1
@@ -234,7 +264,16 @@ class MessageEvent(proto.Message):
             """
 
             class Type(proto.Enum):
-                r"""Indicates whether the message was sent or received."""
+                r"""Indicates whether the message was sent or received.
+
+                Values:
+                    TYPE_UNSPECIFIED (0):
+                        Unknown event type.
+                    SENT (1):
+                        Indicates a sent message.
+                    RECEIVED (2):
+                        Indicates a received message.
+                """
                 TYPE_UNSPECIFIED = 0
                 SENT = 1
                 RECEIVED = 2
@@ -330,6 +369,16 @@ class Link(proto.Message):
         class Type(proto.Enum):
             r"""The relationship of the current span relative to the linked
             span: child, parent, or unspecified.
+
+            Values:
+                TYPE_UNSPECIFIED (0):
+                    The relationship of the two spans is unknown.
+                CHILD_LINKED_SPAN (1):
+                    The linked span is a child of the current
+                    span.
+                PARENT_LINKED_SPAN (2):
+                    The linked span is a parent of the current
+                    span.
             """
             TYPE_UNSPECIFIED = 0
             CHILD_LINKED_SPAN = 1

samples/generated_samples/snippet_metadata_google.devtools.cloudtrace.v1.json

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

samples/generated_samples/snippet_metadata_google.devtools.cloudtrace.v2.json

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