docs: Update inclusive language in the documentation. Also other latest doc updates.

Google APIs · copybara-github · commit 28e0d72b1e74 · 2020-10-22T14:21:00.000-07:00
PiperOrigin-RevId: 338547917
diff --git a/google/api/auth.proto b/google/api/auth.proto
@@ -65,6 +65,7 @@ message AuthenticationRule {
   OAuthRequirements oauth = 2;
 
   // If true, the service accepts API keys without any other credential.
+  // This flag only applies to HTTP and gRPC requests.
   bool allow_without_credential = 5;
 
   // Requirements for additional authentication providers.
diff --git a/google/api/context.proto b/google/api/context.proto
@@ -40,7 +40,7 @@ option objc_class_prefix = "GAPI";
 // Available context types are defined in package
 // `google.rpc.context`.
 //
-// This also provides mechanism to whitelist any protobuf message extension that
+// This also provides mechanism to allowlist any protobuf message extension that
 // can be sent in grpc metadata using “x-goog-ext-<extension_id>-bin” and
 // “x-goog-ext-<extension_id>-jspb” format. For example, list any service
 // specific protobuf types that can appear in grpc metadata as follows in your
diff --git a/google/api/distribution.proto b/google/api/distribution.proto
@@ -175,7 +175,7 @@ message Distribution {
   //
   //     Sum[i=1..n]((x_i - mean)^2)
   //
-  // Knuth, "The Art of Computer Programming", Vol. 2, page 323, 3rd edition
+  // Knuth, "The Art of Computer Programming", Vol. 2, page 232, 3rd edition
   // describes Welford's method for accumulating this sum in one pass.
   //
   // If `count` is zero then this field must be zero.
diff --git a/google/api/launch_stage.proto b/google/api/launch_stage.proto
@@ -45,7 +45,7 @@ enum LaunchStage {
   // for widespread use. By Alpha, all significant design issues are resolved
   // and we are in the process of verifying functionality. Alpha customers
   // need to apply for access, agree to applicable terms, and have their
-  // projects whitelisted. Alpha releases don’t have to be feature complete,
+  // projects allowlisted. Alpha releases don’t have to be feature complete,
   // no SLAs are provided, and there are no technical support obligations, but
   // they will be far enough along that customers can actually use them in
   // test environments or for limited-use tests -- just like they would in
diff --git a/google/api/metric.proto b/google/api/metric.proto
@@ -30,17 +30,6 @@ option objc_class_prefix = "GAPI";
 // deleting or altering it stops data collection and makes the metric type's
 // existing data unusable.
 //
-// The following are specific rules for service defined Monitoring metric
-// descriptors:
-//
-// * `type`, `metric_kind`, `value_type`, `description`, `display_name`,
-//   `launch_stage` fields are all required. The `unit` field must be specified
-//   if the `value_type` is any of DOUBLE, INT64, DISTRIBUTION.
-// * Maximum of default 500 metric descriptors per service is allowed.
-// * Maximum of default 10 labels per metric descriptor is allowed.
-//
-// The default maximum limit can be overridden. Please follow
-// https://cloud.google.com/monitoring/quotas
 message MetricDescriptor {
   // Additional annotations that can be used to guide the usage of a metric.
   message MetricDescriptorMetadata {
@@ -60,6 +49,8 @@ message MetricDescriptor {
   }
 
   // The kind of measurement. It describes how the data is reported.
+  // For information on setting the start time and end time based on
+  // the MetricKind, see [TimeInterval][google.monitoring.v3.TimeInterval].
   enum MetricKind {
     // Do not use this default value.
     METRIC_KIND_UNSPECIFIED = 0;
@@ -108,40 +99,17 @@ message MetricDescriptor {
   string name = 1;
 
   // The metric type, including its DNS name prefix. The type is not
-  // URL-encoded.
-  //
-  // All service defined metrics must be prefixed with the service name, in the
-  // format of `{service name}/{relative metric name}`, such as
-  // `cloudsql.googleapis.com/database/cpu/utilization`. The relative metric
-  // name must follow:
-  //
-  // * Only upper and lower-case letters, digits, '/' and underscores '_' are
-  //   allowed.
-  // * The maximum number of characters allowed for the relative_metric_name is
-  //   100.
-  //
-  // All user-defined metric types have the DNS name
-  // `custom.googleapis.com`, `external.googleapis.com`, or
-  // `logging.googleapis.com/user/`.
-  //
-  // Metric types should use a natural hierarchical grouping. For example:
+  // URL-encoded. All user-defined metric types have the DNS name
+  // `custom.googleapis.com` or `external.googleapis.com`. Metric types should
+  // use a natural hierarchical grouping. For example:
   //
   //     "custom.googleapis.com/invoice/paid/amount"
   //     "external.googleapis.com/prometheus/up"
   //     "appengine.googleapis.com/http/server/response_latencies"
   string type = 8;
 
   // The set of labels that can be used to describe a specific
-  // instance of this metric type.
-  //
-  // The label key name must follow:
-  //
-  // * Only upper and lower-case letters, digits and underscores (_) are
-  //   allowed.
-  // * Label name must start with a letter or digit.
-  // * The maximum length of a label name is 100 characters.
-  //
-  // For example, the
+  // instance of this metric type. For example, the
   // `appengine.googleapis.com/http/server/response_latencies` metric
   // type has a label for the HTTP response code, `response_code`, so
   // you can look at latencies for successful responses or just
diff --git a/google/api/monitored_resource.proto b/google/api/monitored_resource.proto
@@ -33,23 +33,9 @@ option objc_class_prefix = "GAPI";
 // `"gce_instance"` and specifies the use of the labels `"instance_id"` and
 // `"zone"` to identify particular VM instances.
 //
-// Different services can support different monitored resource types.
-//
-// The following are specific rules to service defined monitored resources for
-// Monitoring and Logging:
-//
-// * The `type`, `display_name`, `description`, `labels` and `launch_stage`
-//   fields are all required.
-// * The first label of the monitored resource descriptor must be
-//   `resource_container`. There are legacy monitored resource descritptors
-//   start with `project_id`.
-// * It must include a `location` label.
-// * Maximum of default 5 service defined monitored resource descriptors
-//   is allowed per service.
-// * Maximum of default 10 labels per monitored resource is allowed.
-//
-// The default maximum limit can be overridden. Please follow
-// https://cloud.google.com/monitoring/quotas
+// Different APIs can support different monitored resource types. APIs generally
+// provide a `list` method that returns the monitored resource descriptors used
+// by the API.
 //
 message MonitoredResourceDescriptor {
   // Optional. The resource name of the monitored resource descriptor:
@@ -61,19 +47,7 @@ message MonitoredResourceDescriptor {
   string name = 5;
 
   // Required. The monitored resource type. For example, the type
-  // `cloudsql_database` represents databases in Google Cloud SQL.
-  //
-  // All service defined monitored resource types must be prefixed with the
-  // service name, in the format of `{service name}/{relative resource name}`.
-  // The relative resource name must follow:
-  //
-  // * Only upper and lower-case letters and digits are allowed.
-  // * It must start with upper case character and is recommended to use Upper
-  //   Camel Case style.
-  // * The maximum number of characters allowed for the relative_resource_name
-  //   is 100.
-  //
-  // Note there are legacy service monitored resources not following this rule.
+  // `"cloudsql_database"` represents databases in Google Cloud SQL.
   string type = 1;
 
   // Optional. A concise name for the monitored resource type that might be
@@ -87,16 +61,8 @@ message MonitoredResourceDescriptor {
   string description = 3;
 
   // Required. A set of labels used to describe instances of this monitored
-  // resource type.
-  // The label key name must follow:
-  //
-  // * Only upper and lower-case letters, digits and underscores (_) are
-  //   allowed.
-  // * Label name must start with a letter or digit.
-  // * The maximum length of a label name is 100 characters.
-  //
-  // For example, an individual Google Cloud SQL database is
-  // identified by values for the labels `database_id` and `location`.
+  // resource type. For example, an individual Google Cloud SQL database is
+  // identified by values for the labels `"database_id"` and `"zone"`.
   repeated LabelDescriptor labels = 4;
 
   // Optional. The launch stage of the monitored resource definition.
diff --git a/google/api/monitoring.proto b/google/api/monitoring.proto
@@ -28,37 +28,52 @@ option objc_class_prefix = "GAPI";
 // for monitoring. In the example, a monitored resource and two metrics are
 // defined. The `library.googleapis.com/book/returned_count` metric is sent
 // to both producer and consumer projects, whereas the
-// `library.googleapis.com/book/overdue_count` metric is only sent to the
+// `library.googleapis.com/book/num_overdue` metric is only sent to the
 // consumer project.
 //
 //     monitored_resources:
-//     - type: library.googleapis.com/branch
+//     - type: library.googleapis.com/Branch
+//       display_name: "Library Branch"
+//       description: "A branch of a library."
+//       launch_stage: GA
 //       labels:
-//       - key: /city
-//         description: The city where the library branch is located in.
-//       - key: /name
-//         description: The name of the branch.
+//       - key: resource_container
+//         description: "The Cloud container (ie. project id) for the Branch."
+//       - key: location
+//         description: "The location of the library branch."
+//       - key: branch_id
+//         description: "The id of the branch."
 //     metrics:
 //     - name: library.googleapis.com/book/returned_count
+//       display_name: "Books Returned"
+//       description: "The count of books that have been returned."
+//       launch_stage: GA
 //       metric_kind: DELTA
 //       value_type: INT64
+//       unit: "1"
 //       labels:
-//       - key: /customer_id
-//     - name: library.googleapis.com/book/overdue_count
+//       - key: customer_id
+//         description: "The id of the customer."
+//     - name: library.googleapis.com/book/num_overdue
+//       display_name: "Books Overdue"
+//       description: "The current number of overdue books."
+//       launch_stage: GA
 //       metric_kind: GAUGE
 //       value_type: INT64
+//       unit: "1"
 //       labels:
-//       - key: /customer_id
+//       - key: customer_id
+//         description: "The id of the customer."
 //     monitoring:
 //       producer_destinations:
-//       - monitored_resource: library.googleapis.com/branch
+//       - monitored_resource: library.googleapis.com/Branch
 //         metrics:
 //         - library.googleapis.com/book/returned_count
 //       consumer_destinations:
-//       - monitored_resource: library.googleapis.com/branch
+//       - monitored_resource: library.googleapis.com/Branch
 //         metrics:
 //         - library.googleapis.com/book/returned_count
-//         - library.googleapis.com/book/overdue_count
+//         - library.googleapis.com/book/num_overdue
 message Monitoring {
   // Configuration of a specific monitoring destination (the producer project
   // or the consumer project).
@@ -73,15 +88,15 @@ message Monitoring {
   }
 
   // Monitoring configurations for sending metrics to the producer project.
-  // There can be multiple producer destinations. A monitored resouce type may
+  // There can be multiple producer destinations. A monitored resource type may
   // appear in multiple monitoring destinations if different aggregations are
   // needed for different sets of metrics associated with that monitored
   // resource type. A monitored resource and metric pair may only be used once
   // in the Monitoring configuration.
   repeated MonitoringDestination producer_destinations = 1;
 
   // Monitoring configurations for sending metrics to the consumer project.
-  // There can be multiple consumer destinations. A monitored resouce type may
+  // There can be multiple consumer destinations. A monitored resource type may
   // appear in multiple monitoring destinations if different aggregations are
   // needed for different sets of metrics associated with that monitored
   // resource type. A monitored resource and metric pair may only be used once
diff --git a/google/api/service.proto b/google/api/service.proto
@@ -70,11 +70,7 @@ option objc_class_prefix = "GAPI";
 //         requirements:
 //           provider_id: google_calendar_auth
 message Service {
-  // The semantic version of the service configuration. The config version
-  // affects the interpretation of the service configuration. For example,
-  // certain features are enabled by default for certain config versions.
-  //
-  // The latest config version is `3`.
+  // This field is obsolete. Its value must be set to `3`.
   google.protobuf.UInt32Value config_version = 20;
 
   // The service name, which is a DNS-like logical identifier for the
