docs: Improvements to various message and field descriptions

Google APIs · copybara-github · commit 853cfd33b665 · 2021-08-18T14:01:14.000-07:00
PiperOrigin-RevId: 391604499
diff --git a/google/cloud/bigquery/datatransfer/v1/bigquerydatatransfer_v1.yaml b/google/cloud/bigquery/datatransfer/v1/bigquerydatatransfer_v1.yaml
@@ -10,10 +10,24 @@ documentation:
   summary: |-
     Schedule queries or transfer external data from SaaS applications to Google
     BigQuery on a regular basis.
+  rules:
+  - selector: google.cloud.location.Locations.GetLocation
+    description: Gets information about a location.
+
+  - selector: google.cloud.location.Locations.ListLocations
+    description: Lists information about the supported locations for this service.
 
 authentication:
   rules:
   - selector: 'google.cloud.bigquery.datatransfer.v1.DataTransferService.*'
     oauth:
       canonical_scopes: |-
         https://www.googleapis.com/auth/cloud-platform
+  - selector: google.cloud.location.Locations.GetLocation
+    oauth:
+      canonical_scopes: |-
+        https://www.googleapis.com/auth/cloud-platform
+  - selector: google.cloud.location.Locations.ListLocations
+    oauth:
+      canonical_scopes: |-
+        https://www.googleapis.com/auth/cloud-platform
diff --git a/google/cloud/bigquery/datatransfer/v1/datatransfer.proto b/google/cloud/bigquery/datatransfer/v1/datatransfer.proto
@@ -1,4 +1,4 @@
-// Copyright 2020 Google LLC
+// Copyright 2021 Google LLC
 //
 // Licensed under the Apache License, Version 2.0 (the "License");
 // you may not use this file except in compliance with the License.
@@ -117,7 +117,8 @@ service DataTransferService {
     option (google.api.method_signature) = "name";
   }
 
-  // Returns information about all data transfers in the project.
+  // Returns information about all transfer configs owned by a project in the
+  // specified location.
   rpc ListTransferConfigs(ListTransferConfigsRequest) returns (ListTransferConfigsResponse) {
     option (google.api.http) = {
       get: "/v1/{parent=projects/*/locations/*}/transferConfigs"
@@ -329,9 +330,7 @@ message DataSource {
     // exchanged for a refresh token on the backend.
     GOOGLE_PLUS_AUTHORIZATION_CODE = 2;
 
-    // Use First Party Client OAuth. First Party Client OAuth doesn't require a
-    // refresh token to get an offline access token. Instead, it uses a
-    // client-signed JWT assertion to retrieve an access token.
+    // Use First Party OAuth.
     FIRST_PARTY_OAUTH = 3;
   }
 
@@ -806,14 +805,14 @@ message StartManualTransferRunsRequest {
   message TimeRange {
     // Start time of the range of transfer runs. For example,
     // `"2017-05-25T00:00:00+00:00"`. The start_time must be strictly less than
-    // the end_time. Creates transfer runs where run_time is in the range betwen
-    // start_time (inclusive) and end_time (exlusive).
+    // the end_time. Creates transfer runs where run_time is in the range
+    // between start_time (inclusive) and end_time (exclusive).
     google.protobuf.Timestamp start_time = 1;
 
     // End time of the range of transfer runs. For example,
     // `"2017-05-30T00:00:00+00:00"`. The end_time must not be in the future.
-    // Creates transfer runs where run_time is in the range betwen start_time
-    // (inclusive) and end_time (exlusive).
+    // Creates transfer runs where run_time is in the range between start_time
+    // (inclusive) and end_time (exclusive).
     google.protobuf.Timestamp end_time = 2;
   }
 
diff --git a/google/cloud/bigquery/datatransfer/v1/transfer.proto b/google/cloud/bigquery/datatransfer/v1/transfer.proto
@@ -1,4 +1,4 @@
-// Copyright 2020 Google LLC
+// Copyright 2021 Google LLC
 //
 // Licensed under the Apache License, Version 2.0 (the "License");
 // you may not use this file except in compliance with the License.
@@ -18,6 +18,7 @@ package google.cloud.bigquery.datatransfer.v1;
 
 import "google/api/field_behavior.proto";
 import "google/api/resource.proto";
+import "google/protobuf/duration.proto";
 import "google/protobuf/struct.proto";
 import "google/protobuf/timestamp.proto";
 import "google/rpc/status.proto";
@@ -48,23 +49,23 @@ enum TransferType {
 
 // Represents data transfer run state.
 enum TransferState {
-  // State placeholder.
+  // State placeholder (0).
   TRANSFER_STATE_UNSPECIFIED = 0;
 
   // Data transfer is scheduled and is waiting to be picked up by
-  // data transfer backend.
+  // data transfer backend (2).
   PENDING = 2;
 
-  // Data transfer is in progress.
+  // Data transfer is in progress (3).
   RUNNING = 3;
 
-  // Data transfer completed successfully.
+  // Data transfer completed successfully (4).
   SUCCEEDED = 4;
 
-  // Data transfer failed.
+  // Data transfer failed (5).
   FAILED = 5;
 
-  // Data transfer is cancelled.
+  // Data transfer is cancelled (6).
   CANCELLED = 6;
 }
 
@@ -111,12 +112,11 @@ message TransferConfig {
   };
 
   // The resource name of the transfer config.
-  // Transfer config names have the form of
+  // Transfer config names have the form
   // `projects/{project_id}/locations/{region}/transferConfigs/{config_id}`.
-  // The name is automatically generated based on the config_id specified in
-  // CreateTransferConfigRequest along with project_id and region. If config_id
-  // is not provided, usually a uuid, even though it is not guaranteed or
-  // required, will be generated for config_id.
+  // Where `config_id` is usually a uuid, even though it is not
+  // guaranteed or required. The name is ignored when creating a transfer
+  // config.
   string name = 1;
 
   // The desination of the transfer config.
@@ -131,7 +131,10 @@ message TransferConfig {
   // Data source id. Cannot be changed once data transfer is created.
   string data_source_id = 5;
 
-  // Data transfer specific parameters.
+  // Parameters specific to each data source. For more information see the
+  // bq tab in the 'Setting up a data transfer' section for each data source.
+  // For example the parameters for Cloud Storage transfers are listed here:
+  // https://cloud.google.com/bigquery-transfer/docs/cloud-storage-transfer#bq
   google.protobuf.Struct params = 9;
 
   // Data transfer schedule.
@@ -180,6 +183,9 @@ message TransferConfig {
 
   // Pub/Sub topic where notifications will be sent after transfer runs
   // associated with this transfer config finish.
+  //
+  // The format for specifying a pubsub topic is:
+  // `projects/{project}/topics/{topic}`
   string notification_pubsub_topic = 15;
 
   // Email notifications will be sent according to these preferences
@@ -222,7 +228,10 @@ message TransferRun {
   // Output only. Last time the data transfer run state was updated.
   google.protobuf.Timestamp update_time = 6 [(google.api.field_behavior) = OUTPUT_ONLY];
 
-  // Output only. Data transfer specific parameters.
+  // Output only. Parameters specific to each data source. For more information see the
+  // bq tab in the 'Setting up a data transfer' section for each data source.
+  // For example the parameters for Cloud Storage transfers are listed here:
+  // https://cloud.google.com/bigquery-transfer/docs/cloud-storage-transfer#bq
   google.protobuf.Struct params = 9 [(google.api.field_behavior) = OUTPUT_ONLY];
 
   // Data transfer destination.
@@ -248,7 +257,10 @@ message TransferRun {
   string schedule = 12 [(google.api.field_behavior) = OUTPUT_ONLY];
 
   // Output only. Pub/Sub topic where a notification will be sent after this
-  // transfer run finishes
+  // transfer run finishes.
+  //
+  // The format for specifying a pubsub topic is:
+  // `projects/{project}/topics/{topic}`
   string notification_pubsub_topic = 23 [(google.api.field_behavior) = OUTPUT_ONLY];
 
   // Output only. Email notifications will be sent according to these
