docs: Add documentation for enums (#311)

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

packages/google-cloud-scheduler/google/cloud/scheduler_v1/services/cloud_scheduler/client.py

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

packages/google-cloud-scheduler/google/cloud/scheduler_v1/types/job.py

@@ -160,7 +160,28 @@ class Job(proto.Message):
     """
 
     class State(proto.Enum):
-        r"""State of the job."""
+        r"""State of the job.
+
+        Values:
+            STATE_UNSPECIFIED (0):
+                Unspecified state.
+            ENABLED (1):
+                The job is executing normally.
+            PAUSED (2):
+                The job is paused by the user. It will not execute. A user
+                can intentionally pause the job using
+                [PauseJobRequest][google.cloud.scheduler.v1.PauseJobRequest].
+            DISABLED (3):
+                The job is disabled by the system due to
+                error. The user cannot directly set a job to be
+                disabled.
+            UPDATE_FAILED (4):
+                The job state resulting from a failed
+                [CloudScheduler.UpdateJob][google.cloud.scheduler.v1.CloudScheduler.UpdateJob]
+                operation. To recover a job from this state, retry
+                [CloudScheduler.UpdateJob][google.cloud.scheduler.v1.CloudScheduler.UpdateJob]
+                until a successful response is received.
+        """
         STATE_UNSPECIFIED = 0
         ENABLED = 1
         PAUSED = 2

packages/google-cloud-scheduler/google/cloud/scheduler_v1/types/target.py

@@ -32,7 +32,26 @@
 
 
 class HttpMethod(proto.Enum):
-    r"""The HTTP method used to execute the job."""
+    r"""The HTTP method used to execute the job.
+
+    Values:
+        HTTP_METHOD_UNSPECIFIED (0):
+            HTTP method unspecified. Defaults to POST.
+        POST (1):
+            HTTP POST
+        GET (2):
+            HTTP GET
+        HEAD (3):
+            HTTP HEAD
+        PUT (4):
+            HTTP PUT
+        DELETE (5):
+            HTTP DELETE
+        PATCH (6):
+            HTTP PATCH
+        OPTIONS (7):
+            HTTP OPTIONS
+    """
     HTTP_METHOD_UNSPECIFIED = 0
     POST = 1
     GET = 2

packages/google-cloud-scheduler/google/cloud/scheduler_v1beta1/services/cloud_scheduler/client.py

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

packages/google-cloud-scheduler/google/cloud/scheduler_v1beta1/types/job.py

@@ -181,7 +181,28 @@ class Job(proto.Message):
     """
 
     class State(proto.Enum):
-        r"""State of the job."""
+        r"""State of the job.
+
+        Values:
+            STATE_UNSPECIFIED (0):
+                Unspecified state.
+            ENABLED (1):
+                The job is executing normally.
+            PAUSED (2):
+                The job is paused by the user. It will not execute. A user
+                can intentionally pause the job using
+                [PauseJobRequest][google.cloud.scheduler.v1beta1.PauseJobRequest].
+            DISABLED (3):
+                The job is disabled by the system due to
+                error. The user cannot directly set a job to be
+                disabled.
+            UPDATE_FAILED (4):
+                The job state resulting from a failed
+                [CloudScheduler.UpdateJob][google.cloud.scheduler.v1beta1.CloudScheduler.UpdateJob]
+                operation. To recover a job from this state, retry
+                [CloudScheduler.UpdateJob][google.cloud.scheduler.v1beta1.CloudScheduler.UpdateJob]
+                until a successful response is received.
+        """
         STATE_UNSPECIFIED = 0
         ENABLED = 1
         PAUSED = 2

packages/google-cloud-scheduler/google/cloud/scheduler_v1beta1/types/target.py

@@ -32,7 +32,26 @@
 
 
 class HttpMethod(proto.Enum):
-    r"""The HTTP method used to execute the job."""
+    r"""The HTTP method used to execute the job.
+
+    Values:
+        HTTP_METHOD_UNSPECIFIED (0):
+            HTTP method unspecified. Defaults to POST.
+        POST (1):
+            HTTP POST
+        GET (2):
+            HTTP GET
+        HEAD (3):
+            HTTP HEAD
+        PUT (4):
+            HTTP PUT
+        DELETE (5):
+            HTTP DELETE
+        PATCH (6):
+            HTTP PATCH
+        OPTIONS (7):
+            HTTP OPTIONS
+    """
     HTTP_METHOD_UNSPECIFIED = 0
     POST = 1
     GET = 2

packages/google-cloud-scheduler/samples/generated_samples/snippet_metadata_google.cloud.scheduler.v1.json

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

packages/google-cloud-scheduler/samples/generated_samples/snippet_metadata_google.cloud.scheduler.v1beta1.json

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