docs: [scheduler] update comments (#5982)

* docs: update comments
docs: annotate output-only fields as such

PiperOrigin-RevId: 719865415

Source-Link: googleapis/googleapis@47444ff

Source-Link: googleapis/googleapis-gen@2166b70
Copy-Tag: eyJwIjoicGFja2FnZXMvZ29vZ2xlLWNsb3VkLXNjaGVkdWxlci8uT3dsQm90LnlhbWwiLCJoIjoiMjE2NmI3MDNkNTAwMmZkOWZjYzE4Y2QwMzk5NTZkYmUwMWQ1N2ZjMSJ9

* 🦉 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/protos/google/cloud/scheduler/v1/cloudscheduler.proto

@@ -161,11 +161,7 @@ message ListJobsRequest {
   // request the next page of results, page_token must be the value of
   // [next_page_token][google.cloud.scheduler.v1.ListJobsResponse.next_page_token]
   // returned from the previous call to
-  // [ListJobs][google.cloud.scheduler.v1.CloudScheduler.ListJobs]. It is an
-  // error to switch the value of
-  // [filter][google.cloud.scheduler.v1.ListJobsRequest.filter] or
-  // [order_by][google.cloud.scheduler.v1.ListJobsRequest.order_by] while
-  // iterating through pages.
+  // [ListJobs][google.cloud.scheduler.v1.CloudScheduler.ListJobs].
   string page_token = 6;
 }
 

packages/google-cloud-scheduler/protos/google/cloud/scheduler/v1/job.proto

@@ -16,6 +16,7 @@ syntax = "proto3";
 
 package google.cloud.scheduler.v1;
 
+import "google/api/field_behavior.proto";
 import "google/api/resource.proto";
 import "google/cloud/scheduler/v1/target.proto";
 import "google/protobuf/duration.proto";
@@ -33,6 +34,8 @@ message Job {
   option (google.api.resource) = {
     type: "cloudscheduler.googleapis.com/Job"
     pattern: "projects/{project}/locations/{location}/jobs/{job}"
+    plural: "jobs"
+    singular: "job"
   };
 
   // State of the job.
@@ -125,7 +128,11 @@ message Job {
   // If [retry_count][google.cloud.scheduler.v1.RetryConfig.retry_count] > 0 and
   // a job attempt fails, the job will be tried a total of
   // [retry_count][google.cloud.scheduler.v1.RetryConfig.retry_count] times,
-  // with exponential backoff, until the next scheduled start time.
+  // with exponential backoff, until the next scheduled start time. If
+  // retry_count is 0, a job attempt will not be retried if it fails. Instead
+  // the Cloud Scheduler system will wait for the next scheduled execution time.
+  // Setting retry_count to 0 does not prevent failed jobs from running
+  // according to schedule after the failure.
   string schedule = 20;
 
   // Specifies the time zone to be used in interpreting
@@ -141,21 +148,24 @@ message Job {
   string time_zone = 21;
 
   // Output only. The creation time of the job.
-  google.protobuf.Timestamp user_update_time = 9;
+  google.protobuf.Timestamp user_update_time = 9
+      [(google.api.field_behavior) = OUTPUT_ONLY];
 
   // Output only. State of the job.
-  State state = 10;
+  State state = 10 [(google.api.field_behavior) = OUTPUT_ONLY];
 
   // Output only. The response from the target for the last attempted execution.
-  google.rpc.Status status = 11;
+  google.rpc.Status status = 11 [(google.api.field_behavior) = OUTPUT_ONLY];
 
   // Output only. The next time the job is scheduled. Note that this may be a
   // retry of a previously failed attempt or the next execution time
   // according to the schedule.
-  google.protobuf.Timestamp schedule_time = 17;
+  google.protobuf.Timestamp schedule_time = 17
+      [(google.api.field_behavior) = OUTPUT_ONLY];
 
   // Output only. The time the last job attempt started.
-  google.protobuf.Timestamp last_attempt_time = 18;
+  google.protobuf.Timestamp last_attempt_time = 18
+      [(google.api.field_behavior) = OUTPUT_ONLY];
 
   // Settings that determine the retry behavior.
   RetryConfig retry_config = 19;
@@ -198,9 +208,10 @@ message RetryConfig {
   //
   // The default value of retry_count is zero.
   //
-  // If retry_count is zero, a job attempt will *not* be retried if
+  // If retry_count is 0, a job attempt will not be retried if
   // it fails. Instead the Cloud Scheduler system will wait for the
-  // next scheduled execution time.
+  // next scheduled execution time. Setting retry_count to 0 does not prevent
+  // failed jobs from running according to schedule after the failure.
   //
   // If retry_count is set to a non-zero number then Cloud Scheduler
   // will retry failed attempts, using exponential backoff,
@@ -245,7 +256,7 @@ message RetryConfig {
   // [min_backoff_duration][google.cloud.scheduler.v1.RetryConfig.min_backoff_duration]
   // is 10s,
   // [max_backoff_duration][google.cloud.scheduler.v1.RetryConfig.max_backoff_duration]
-  // is 300s, and `max_doublings` is 3, then the a job will first be retried in
+  // is 300s, and `max_doublings` is 3, then the job will first be retried in
   // 10s. The retry interval will double three times, and then increase linearly
   // by 2^3 * 10s.  Finally, the job will retry at intervals of
   // [max_backoff_duration][google.cloud.scheduler.v1.RetryConfig.max_backoff_duration]

packages/google-cloud-scheduler/protos/google/cloud/scheduler/v1/target.proto

@@ -46,14 +46,20 @@ message HttpTarget {
   // Which HTTP method to use for the request.
   HttpMethod http_method = 2;
 
+  // HTTP request headers.
+  //
+  // This map contains the header field names and values.
+  //
   // The user can specify HTTP request headers to send with the job's
-  // HTTP request. This map contains the header field names and
-  // values. Repeated headers are not supported, but a header value can
-  // contain commas. These headers represent a subset of the headers
-  // that will accompany the job's HTTP request. Some HTTP request
-  // headers will be ignored or replaced. A partial list of headers that
-  // will be ignored or replaced is below:
-  // - Host: This will be computed by Cloud Scheduler and derived from
+  // HTTP request. Repeated headers are not supported, but a header value can
+  // contain commas.
+  //
+  // The following headers represent a subset of the headers
+  // that accompany the job's HTTP request. Some HTTP request
+  // headers are ignored or replaced. A partial list of headers that
+  // are ignored or replaced is below:
+  //
+  // * Host: This will be computed by Cloud Scheduler and derived from
   // [uri][google.cloud.scheduler.v1.HttpTarget.uri].
   // * `Content-Length`: This will be computed by Cloud Scheduler.
   // * `User-Agent`: This will be set to `"Google-Cloud-Scheduler"`.
@@ -65,6 +71,15 @@ message HttpTarget {
   // the unix-cron format, this header will contain the job schedule as an
   // offset of UTC parsed according to RFC3339.
   //
+  // If the job has a [body][google.cloud.scheduler.v1.HttpTarget.body] and the
+  // following headers are not set by the user, Cloud Scheduler sets default
+  // values:
+  //
+  // * `Content-Type`: This will be set to `"application/octet-stream"`. You
+  //   can override this default by explicitly setting `Content-Type` to a
+  //   particular media type when creating the job. For example, you can set
+  //   `Content-Type` to `"application/json"`.
+  //
   // The total size of headers must be less than 80KB.
   map<string, string> headers = 3;
 
@@ -144,20 +159,18 @@ message AppEngineHttpTarget {
   // the unix-cron format, this header will contain the job schedule as an
   // offset of UTC parsed according to RFC3339.
   //
-  // If the job has an
-  // [body][google.cloud.scheduler.v1.AppEngineHttpTarget.body], Cloud Scheduler
-  // sets the following headers:
+  // If the job has a [body][google.cloud.scheduler.v1.AppEngineHttpTarget.body]
+  // and the following headers are not set by the user, Cloud Scheduler sets
+  // default values:
   //
-  // * `Content-Type`: By default, the `Content-Type` header is set to
-  //   `"application/octet-stream"`. The default can be overridden by explictly
-  //   setting `Content-Type` to a particular media type when the job is
-  //   created.
-  //   For example, `Content-Type` can be set to `"application/json"`.
-  // * `Content-Length`: This is computed by Cloud Scheduler. This value is
-  //   output only. It cannot be changed.
+  // * `Content-Type`: This will be set to `"application/octet-stream"`. You
+  //   can override this default by explicitly setting `Content-Type` to a
+  //   particular media type when creating the job. For example, you can set
+  //   `Content-Type` to `"application/json"`.
   //
   // The headers below are output only. They cannot be set or overridden:
   //
+  // * `Content-Length`: This is computed by Cloud Scheduler.
   // * `X-Google-*`: For Google internal use only.
   // * `X-AppEngine-*`: For Google internal use only.
   //

packages/google-cloud-scheduler/samples/generated/v1/cloud_scheduler.list_jobs.js

@@ -47,11 +47,7 @@ function main(parent) {
    *  request the next page of results, page_token must be the value of
    *  next_page_token google.cloud.scheduler.v1.ListJobsResponse.next_page_token 
    *  returned from the previous call to
-   *  ListJobs google.cloud.scheduler.v1.CloudScheduler.ListJobs. It is an
-   *  error to switch the value of
-   *  filter google.cloud.scheduler.v1.ListJobsRequest.filter  or
-   *  order_by google.cloud.scheduler.v1.ListJobsRequest.order_by  while
-   *  iterating through pages.
+   *  ListJobs google.cloud.scheduler.v1.CloudScheduler.ListJobs.
    */
   // const pageToken = 'abc123'
 

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

@@ -22,7 +22,7 @@
             "segments": [
                 {
                     "start": 25,
-                    "end": 77,
+                    "end": 73,
                     "type": "FULL"
                 }
             ],

packages/google-cloud-scheduler/src/v1/cloud_scheduler_client.ts

@@ -1045,11 +1045,7 @@ export class CloudSchedulerClient {
    *   request the next page of results, page_token must be the value of
    *   {@link protos.google.cloud.scheduler.v1.ListJobsResponse.next_page_token|next_page_token}
    *   returned from the previous call to
-   *   {@link protos.google.cloud.scheduler.v1.CloudScheduler.ListJobs|ListJobs}. It is an
-   *   error to switch the value of
-   *   {@link protos.google.cloud.scheduler.v1.ListJobsRequest.filter|filter} or
-   *   {@link protos.google.cloud.scheduler.v1.ListJobsRequest.order_by|order_by} while
-   *   iterating through pages.
+   *   {@link protos.google.cloud.scheduler.v1.CloudScheduler.ListJobs|ListJobs}.
    * @param {object} [options]
    *   Call options. See {@link https://googleapis.dev/nodejs/google-gax/latest/interfaces/CallOptions.html|CallOptions} for more details.
    * @returns {Promise} - The promise which resolves to an array.
@@ -1149,11 +1145,7 @@ export class CloudSchedulerClient {
    *   request the next page of results, page_token must be the value of
    *   {@link protos.google.cloud.scheduler.v1.ListJobsResponse.next_page_token|next_page_token}
    *   returned from the previous call to
-   *   {@link protos.google.cloud.scheduler.v1.CloudScheduler.ListJobs|ListJobs}. It is an
-   *   error to switch the value of
-   *   {@link protos.google.cloud.scheduler.v1.ListJobsRequest.filter|filter} or
-   *   {@link protos.google.cloud.scheduler.v1.ListJobsRequest.order_by|order_by} while
-   *   iterating through pages.
+   *   {@link protos.google.cloud.scheduler.v1.CloudScheduler.ListJobs|ListJobs}.
    * @param {object} [options]
    *   Call options. See {@link https://googleapis.dev/nodejs/google-gax/latest/interfaces/CallOptions.html|CallOptions} for more details.
    * @returns {Stream}
@@ -1209,11 +1201,7 @@ export class CloudSchedulerClient {
    *   request the next page of results, page_token must be the value of
    *   {@link protos.google.cloud.scheduler.v1.ListJobsResponse.next_page_token|next_page_token}
    *   returned from the previous call to
-   *   {@link protos.google.cloud.scheduler.v1.CloudScheduler.ListJobs|ListJobs}. It is an
-   *   error to switch the value of
-   *   {@link protos.google.cloud.scheduler.v1.ListJobsRequest.filter|filter} or
-   *   {@link protos.google.cloud.scheduler.v1.ListJobsRequest.order_by|order_by} while
-   *   iterating through pages.
+   *   {@link protos.google.cloud.scheduler.v1.CloudScheduler.ListJobs|ListJobs}.
    * @param {object} [options]
    *   Call options. See {@link https://googleapis.dev/nodejs/google-gax/latest/interfaces/CallOptions.html|CallOptions} for more details.
    * @returns {Object}