docs: Documentation improvements

Google APIs · copybara-github · commit fee4e43dc76d · 2024-06-05T00:51:11.000-07:00
PiperOrigin-RevId: 640429278
diff --git a/google/cloud/batch/v1/job.proto b/google/cloud/batch/v1/job.proto
@@ -419,9 +419,9 @@ message AllocationPolicy {
       string instance_template = 2;
     }
 
-    // Set this field true if users want Batch to help fetch drivers from a
-    // third party location and install them for GPUs specified in
-    // policy.accelerators or instance_template on their behalf. Default is
+    // Set this field true if you want Batch to help fetch drivers from a third
+    // party location and install them for GPUs specified in
+    // `policy.accelerators` or `instance_template` on your behalf. Default is
     // false.
     //
     // For Container-Optimized Image cases, Batch will install the
diff --git a/google/cloud/batch/v1/task.proto b/google/cloud/batch/v1/task.proto
@@ -108,12 +108,11 @@ message TaskExecution {
   // due to the following reasons, the exit code will be 50000.
   //
   // Otherwise, it can be from different sources:
-  // - Batch known failures as
+  // * Batch known failures:
   // https://cloud.google.com/batch/docs/troubleshooting#reserved-exit-codes.
-  // - Batch runnable execution failures: You can rely on Batch logs for further
-  // diagnose: https://cloud.google.com/batch/docs/analyze-job-using-logs.
-  // If there are multiple runnables failures, Batch only exposes the first
-  // error caught for now.
+  // * Batch runnable execution failures; you can rely on Batch logs to further
+  // diagnose: https://cloud.google.com/batch/docs/analyze-job-using-logs. If
+  // there are multiple runnables failures, Batch only exposes the first error.
   int32 exit_code = 1;
 }
 
@@ -341,10 +340,15 @@ message TaskSpec {
   // ComputeResource requirements.
   ComputeResource compute_resource = 3;
 
-  // Maximum duration the task should run.
-  // The task will be killed and marked as FAILED if over this limit.
-  // The valid value range for max_run_duration in seconds is [0,
-  // 315576000000.999999999],
+  // Maximum duration the task should run before being automatically retried
+  // (if enabled) or automatically failed. Format the value of this field
+  // as a time limit in seconds followed by `s`&mdash;for example, `3600s`
+  // for 1 hour. The field accepts any value between 0 and the maximum listed
+  // for the `Duration` field type at
+  // https://protobuf.dev/reference/protobuf/google.protobuf/#duration; however,
+  // the actual maximum run time for a job will be limited to the maximum run
+  // time for a job listed at
+  // https://cloud.google.com/batch/quotas#max-job-duration.
   google.protobuf.Duration max_run_duration = 4;
 
   // Maximum number of retries on failures.
