docs(scheduler): change docstring formatting, add API proto annotations (via synth) (#9459)

Author: yoshi-automation

scheduler/google/cloud/scheduler_v1/gapic/cloud_scheduler_client.py

@@ -251,9 +251,7 @@ def list_jobs(
             ...         pass
 
         Args:
-            parent (str): Required.
-
-                The location name. For example:
+            parent (str): Required. The location name. For example:
                 ``projects/PROJECT_ID/locations/LOCATION_ID``.
             page_size (int): The maximum number of resources contained in the
                 underlying API response. If page streaming is performed per-
@@ -342,9 +340,7 @@ def get_job(
             >>> response = client.get_job(name)
 
         Args:
-            name (str): Required.
-
-                The job name. For example:
+            name (str): Required. The job name. For example:
                 ``projects/PROJECT_ID/locations/LOCATION_ID/jobs/JOB_ID``.
             retry (Optional[google.api_core.retry.Retry]):  A retry object used
                 to retry requests. If ``None`` is specified, requests will
@@ -418,16 +414,12 @@ def create_job(
             >>> response = client.create_job(parent, job)
 
         Args:
-            parent (str): Required.
-
-                The location name. For example:
+            parent (str): Required. The location name. For example:
                 ``projects/PROJECT_ID/locations/LOCATION_ID``.
-            job (Union[dict, ~google.cloud.scheduler_v1.types.Job]): Required.
-
-                The job to add. The user can optionally specify a name for the job in
-                ``name``. ``name`` cannot be the same as an existing job. If a name is
-                not specified then the system will generate a random unique name that
-                will be returned (``name``) in the response.
+            job (Union[dict, ~google.cloud.scheduler_v1.types.Job]): Required. The job to add. The user can optionally specify a name for the
+                job in ``name``. ``name`` cannot be the same as an existing job. If a
+                name is not specified then the system will generate a random unique name
+                that will be returned (``name``) in the response.
 
                 If a dict is provided, it must be of the same form as the protobuf
                 message :class:`~google.cloud.scheduler_v1.types.Job`
@@ -512,9 +504,7 @@ def update_job(
             >>> response = client.update_job(job, update_mask)
 
         Args:
-            job (Union[dict, ~google.cloud.scheduler_v1.types.Job]): Required.
-
-                The new job properties. ``name`` must be specified.
+            job (Union[dict, ~google.cloud.scheduler_v1.types.Job]): Required. The new job properties. ``name`` must be specified.
 
                 Output only fields cannot be modified using UpdateJob. Any value
                 specified for an output only field will be ignored.
@@ -593,9 +583,7 @@ def delete_job(
             >>> client.delete_job(name)
 
         Args:
-            name (str): Required.
-
-                The job name. For example:
+            name (str): Required. The job name. For example:
                 ``projects/PROJECT_ID/locations/LOCATION_ID/jobs/JOB_ID``.
             retry (Optional[google.api_core.retry.Retry]):  A retry object used
                 to retry requests. If ``None`` is specified, requests will
@@ -667,9 +655,7 @@ def pause_job(
             >>> response = client.pause_job(name)
 
         Args:
-            name (str): Required.
-
-                The job name. For example:
+            name (str): Required. The job name. For example:
                 ``projects/PROJECT_ID/locations/LOCATION_ID/jobs/JOB_ID``.
             retry (Optional[google.api_core.retry.Retry]):  A retry object used
                 to retry requests. If ``None`` is specified, requests will
@@ -744,9 +730,7 @@ def resume_job(
             >>> response = client.resume_job(name)
 
         Args:
-            name (str): Required.
-
-                The job name. For example:
+            name (str): Required. The job name. For example:
                 ``projects/PROJECT_ID/locations/LOCATION_ID/jobs/JOB_ID``.
             retry (Optional[google.api_core.retry.Retry]):  A retry object used
                 to retry requests. If ``None`` is specified, requests will
@@ -819,9 +803,7 @@ def run_job(
             >>> response = client.run_job(name)
 
         Args:
-            name (str): Required.
-
-                The job name. For example:
+            name (str): Required. The job name. For example:
                 ``projects/PROJECT_ID/locations/LOCATION_ID/jobs/JOB_ID``.
             retry (Optional[google.api_core.retry.Retry]):  A retry object used
                 to retry requests. If ``None`` is specified, requests will

scheduler/google/cloud/scheduler_v1/proto/cloudscheduler.proto

@@ -18,6 +18,8 @@ syntax = "proto3";
 package google.cloud.scheduler.v1;
 
 import "google/api/annotations.proto";
+import "google/api/client.proto";
+import "google/api/field_behavior.proto";
 import "google/api/resource.proto";
 import "google/cloud/scheduler/v1/job.proto";
 import "google/protobuf/empty.proto";
@@ -32,18 +34,23 @@ option objc_class_prefix = "SCHEDULER";
 // The Cloud Scheduler API allows external entities to reliably
 // schedule asynchronous jobs.
 service CloudScheduler {
+  option (google.api.default_host) = "cloudscheduler.googleapis.com";
+  option (google.api.oauth_scopes) = "https://www.googleapis.com/auth/cloud-platform";
+
   // Lists jobs.
   rpc ListJobs(ListJobsRequest) returns (ListJobsResponse) {
     option (google.api.http) = {
       get: "/v1/{parent=projects/*/locations/*}/jobs"
     };
+    option (google.api.method_signature) = "parent";
   }
 
   // Gets a job.
   rpc GetJob(GetJobRequest) returns (Job) {
     option (google.api.http) = {
       get: "/v1/{name=projects/*/locations/*/jobs/*}"
     };
+    option (google.api.method_signature) = "name";
   }
 
   // Creates a job.
@@ -52,6 +59,7 @@ service CloudScheduler {
       post: "/v1/{parent=projects/*/locations/*}/jobs"
       body: "job"
     };
+    option (google.api.method_signature) = "parent,job";
   }
 
   // Updates a job.
@@ -68,13 +76,15 @@ service CloudScheduler {
       patch: "/v1/{job.name=projects/*/locations/*/jobs/*}"
       body: "job"
     };
+    option (google.api.method_signature) = "job,update_mask";
   }
 
   // Deletes a job.
   rpc DeleteJob(DeleteJobRequest) returns (google.protobuf.Empty) {
     option (google.api.http) = {
       delete: "/v1/{name=projects/*/locations/*/jobs/*}"
     };
+    option (google.api.method_signature) = "name";
   }
 
   // Pauses a job.
@@ -89,6 +99,7 @@ service CloudScheduler {
       post: "/v1/{name=projects/*/locations/*/jobs/*}:pause"
       body: "*"
     };
+    option (google.api.method_signature) = "name";
   }
 
   // Resume a job.
@@ -102,6 +113,7 @@ service CloudScheduler {
       post: "/v1/{name=projects/*/locations/*/jobs/*}:resume"
       body: "*"
     };
+    option (google.api.method_signature) = "name";
   }
 
   // Forces a job to run now.
@@ -113,16 +125,20 @@ service CloudScheduler {
       post: "/v1/{name=projects/*/locations/*/jobs/*}:run"
       body: "*"
     };
+    option (google.api.method_signature) = "name";
   }
 }
 
 // Request message for listing jobs using [ListJobs][google.cloud.scheduler.v1.CloudScheduler.ListJobs].
 message ListJobsRequest {
-  // Required.
-  //
-  // The location name. For example:
+  // Required. The location name. For example:
   // `projects/PROJECT_ID/locations/LOCATION_ID`.
-  string parent = 1;
+  string parent = 1 [
+    (google.api.field_behavior) = REQUIRED,
+    (google.api.resource_reference) = {
+      child_type: "locations.googleapis.com/Location"
+    }
+  ];
 
   // Requested page size.
   //
@@ -159,79 +175,94 @@ message ListJobsResponse {
 
 // Request message for [GetJob][google.cloud.scheduler.v1.CloudScheduler.GetJob].
 message GetJobRequest {
-  // Required.
-  //
-  // The job name. For example:
+  // Required. The job name. For example:
   // `projects/PROJECT_ID/locations/LOCATION_ID/jobs/JOB_ID`.
-  string name = 1;
+  string name = 1 [
+    (google.api.field_behavior) = REQUIRED,
+    (google.api.resource_reference) = {
+      type: "cloudscheduler.googleapis.com/Job"
+    }
+  ];
 }
 
 // Request message for [CreateJob][google.cloud.scheduler.v1.CloudScheduler.CreateJob].
 message CreateJobRequest {
-  // Required.
-  //
-  // The location name. For example:
+  // Required. The location name. For example:
   // `projects/PROJECT_ID/locations/LOCATION_ID`.
-  string parent = 1;
+  string parent = 1 [
+    (google.api.field_behavior) = REQUIRED,
+    (google.api.resource_reference) = {
+      child_type: "locations.googleapis.com/Location"
+    }
+  ];
 
-  // Required.
-  //
-  // The job to add. The user can optionally specify a name for the
+  // Required. The job to add. The user can optionally specify a name for the
   // job in [name][google.cloud.scheduler.v1.Job.name]. [name][google.cloud.scheduler.v1.Job.name] cannot be the same as an
   // existing job. If a name is not specified then the system will
   // generate a random unique name that will be returned
   // ([name][google.cloud.scheduler.v1.Job.name]) in the response.
-  Job job = 2;
+  Job job = 2 [(google.api.field_behavior) = REQUIRED];
 }
 
 // Request message for [UpdateJob][google.cloud.scheduler.v1.CloudScheduler.UpdateJob].
 message UpdateJobRequest {
-  // Required.
-  //
-  // The new job properties. [name][google.cloud.scheduler.v1.Job.name] must be specified.
+  // Required. The new job properties. [name][google.cloud.scheduler.v1.Job.name] must be specified.
   //
   // Output only fields cannot be modified using UpdateJob.
   // Any value specified for an output only field will be ignored.
-  Job job = 1;
+  Job job = 1 [(google.api.field_behavior) = REQUIRED];
 
   // A  mask used to specify which fields of the job are being updated.
-  google.protobuf.FieldMask update_mask = 2;
+  google.protobuf.FieldMask update_mask = 2
+    [(google.api.field_behavior) = REQUIRED];
 }
 
 // Request message for deleting a job using
 // [DeleteJob][google.cloud.scheduler.v1.CloudScheduler.DeleteJob].
 message DeleteJobRequest {
-  // Required.
-  //
-  // The job name. For example:
+  // Required. The job name. For example:
   // `projects/PROJECT_ID/locations/LOCATION_ID/jobs/JOB_ID`.
-  string name = 1;
+  string name = 1 [
+    (google.api.field_behavior) = REQUIRED,
+    (google.api.resource_reference) = {
+      type: "cloudscheduler.googleapis.com/Job"
+    }
+  ];
 }
 
 // Request message for [PauseJob][google.cloud.scheduler.v1.CloudScheduler.PauseJob].
 message PauseJobRequest {
-  // Required.
-  //
-  // The job name. For example:
+  // Required. The job name. For example:
   // `projects/PROJECT_ID/locations/LOCATION_ID/jobs/JOB_ID`.
-  string name = 1;
+  string name = 1 [
+    (google.api.field_behavior) = REQUIRED,
+    (google.api.resource_reference) = {
+      type: "cloudscheduler.googleapis.com/Job"
+    }
+  ];
 }
 
 // Request message for [ResumeJob][google.cloud.scheduler.v1.CloudScheduler.ResumeJob].
 message ResumeJobRequest {
-  // Required.
-  //
-  // The job name. For example:
+  // Required. The job name. For example:
   // `projects/PROJECT_ID/locations/LOCATION_ID/jobs/JOB_ID`.
-  string name = 1;
+  string name = 1 [
+    (google.api.field_behavior) = REQUIRED,
+    (google.api.resource_reference) = {
+      type: "cloudscheduler.googleapis.com/Job"
+    }
+  ];
 }
 
 // Request message for forcing a job to run now using
 // [RunJob][google.cloud.scheduler.v1.CloudScheduler.RunJob].
 message RunJobRequest {
-  // Required.
-  //
-  // The job name. For example:
+  // Required. The job name. For example:
   // `projects/PROJECT_ID/locations/LOCATION_ID/jobs/JOB_ID`.
-  string name = 1;
+  string name = 1 [
+    (google.api.field_behavior) = REQUIRED,
+    (google.api.resource_reference) = {
+      type: "cloudscheduler.googleapis.com/Job"
+    }
+  ];
 }