docs: Update documentation comments to match tone and style with the rest of Cloud documentation

google-cloud-channel/src/main/java/com/google/cloud/channel/v1/package-info.java

@@ -19,25 +19,23 @@
  *
  * <p>======================= CloudChannelServiceClient =======================
  *
- * <p>Service Description: CloudChannelService enables Google cloud resellers and distributors to
- * manage their customers, channel partners, entitlements and reports.
+ * <p>Service Description: CloudChannelService lets Google cloud resellers and distributors manage
+ * their customers, channel partners, entitlements, and reports.
  *
- * <p>Using this service: 1. Resellers or distributors can manage a customer entity. 2. Distributors
- * can register an authorized reseller in their channel and then enable delegated admin access for
- * the reseller. 3. Resellers or distributors can manage entitlements for their customers.
+ * <p>Using this service: 1. Resellers and distributors can manage a customer entity. 2.
+ * Distributors can register an authorized reseller in their channel and provide them with delegated
+ * admin access. 3. Resellers and distributors can manage customer entitlements.
  *
- * <p>The service primarily exposes the following resources: -
- * [Customer][google.cloud.channel.v1.Customer]s: A Customer represents an entity managed by a
- * reseller or distributor. A customer typically represents an enterprise. In an n-tier resale
- * channel hierarchy, customers are generally represented as leaf nodes. Customers primarily have an
- * Entitlement sub-resource discussed below.
+ * <p>CloudChannelService exposes the following resources: -
+ * [Customer][google.cloud.channel.v1.Customer]s: An entity?usually an enterprise?managed by a
+ * reseller or distributor.
  *
- * <p>- [Entitlement][google.cloud.channel.v1.Entitlement]s: An Entitlement represents an entity
- * which provides a customer means to start using a service. Entitlements are created or updated as
- * a result of a successful fulfillment.
+ * <p>- [Entitlement][google.cloud.channel.v1.Entitlement]s: An entity that provides a customer with
+ * the means to use a service. Entitlements are created or updated as a result of a successful
+ * fulfillment.
  *
- * <p>- [ChannelPartnerLink][google.cloud.channel.v1.ChannelPartnerLink]s: A ChannelPartnerLink is
- * an entity that identifies links between distributors and their indirect resellers in a channel.
+ * <p>- [ChannelPartnerLink][google.cloud.channel.v1.ChannelPartnerLink]s: An entity that identifies
+ * links between distributors and their indirect resellers in a channel.
  *
  * <p>Sample for CloudChannelServiceClient:
  *

proto-google-cloud-channel-v1/src/main/java/com/google/cloud/channel/v1/ActivateEntitlementRequest.java

@@ -126,7 +126,7 @@ public static final com.google.protobuf.Descriptors.Descriptor getDescriptor() {
    *
    * <pre>
    * Required. The resource name of the entitlement to activate.
-   * The name takes the format:
+   * Name uses the format:
    * accounts/{account_id}/customers/{customer_id}/entitlements/{entitlement_id}
    * </pre>
    *
@@ -151,7 +151,7 @@ public java.lang.String getName() {
    *
    * <pre>
    * Required. The resource name of the entitlement to activate.
-   * The name takes the format:
+   * Name uses the format:
    * accounts/{account_id}/customers/{customer_id}/entitlements/{entitlement_id}
    * </pre>
    *
@@ -178,13 +178,12 @@ public com.google.protobuf.ByteString getNameBytes() {
    *
    *
    * <pre>
-   * Optional. An optional request ID to identify requests. Specify a unique request ID so
-   * that if you must retry your request, the server will know to ignore the
-   * request if it has already been completed.
-   * For example, consider a situation where you make an initial request and
-   * the request times out. If you make the request again with the same
-   * request ID, the server can check if the original operation with the same
-   * request ID was received, and if so, will ignore the second request.
+   * Optional. You can specify an optional unique request ID, and if you need to retry
+   * your request, the server will know to ignore the request if it's complete.
+   * For example, you make an initial request and the request times out. If you
+   * make the request again with the same request ID, the server can check if
+   * it received the original operation with the same request ID. If it did, it
+   * will ignore the second request.
    * The request ID must be a valid [UUID](https://tools.ietf.org/html/rfc4122)
    * with the exception that zero UUID is not supported
    * (`00000000-0000-0000-0000-000000000000`).
@@ -210,13 +209,12 @@ public java.lang.String getRequestId() {
    *
    *
    * <pre>
-   * Optional. An optional request ID to identify requests. Specify a unique request ID so
-   * that if you must retry your request, the server will know to ignore the
-   * request if it has already been completed.
-   * For example, consider a situation where you make an initial request and
-   * the request times out. If you make the request again with the same
-   * request ID, the server can check if the original operation with the same
-   * request ID was received, and if so, will ignore the second request.
+   * Optional. You can specify an optional unique request ID, and if you need to retry
+   * your request, the server will know to ignore the request if it's complete.
+   * For example, you make an initial request and the request times out. If you
+   * make the request again with the same request ID, the server can check if
+   * it received the original operation with the same request ID. If it did, it
+   * will ignore the second request.
    * The request ID must be a valid [UUID](https://tools.ietf.org/html/rfc4122)
    * with the exception that zero UUID is not supported
    * (`00000000-0000-0000-0000-000000000000`).
@@ -580,7 +578,7 @@ public Builder mergeFrom(
      *
      * <pre>
      * Required. The resource name of the entitlement to activate.
-     * The name takes the format:
+     * Name uses the format:
      * accounts/{account_id}/customers/{customer_id}/entitlements/{entitlement_id}
      * </pre>
      *
@@ -604,7 +602,7 @@ public java.lang.String getName() {
      *
      * <pre>
      * Required. The resource name of the entitlement to activate.
-     * The name takes the format:
+     * Name uses the format:
      * accounts/{account_id}/customers/{customer_id}/entitlements/{entitlement_id}
      * </pre>
      *
@@ -628,7 +626,7 @@ public com.google.protobuf.ByteString getNameBytes() {
      *
      * <pre>
      * Required. The resource name of the entitlement to activate.
-     * The name takes the format:
+     * Name uses the format:
      * accounts/{account_id}/customers/{customer_id}/entitlements/{entitlement_id}
      * </pre>
      *
@@ -651,7 +649,7 @@ public Builder setName(java.lang.String value) {
      *
      * <pre>
      * Required. The resource name of the entitlement to activate.
-     * The name takes the format:
+     * Name uses the format:
      * accounts/{account_id}/customers/{customer_id}/entitlements/{entitlement_id}
      * </pre>
      *
@@ -670,7 +668,7 @@ public Builder clearName() {
      *
      * <pre>
      * Required. The resource name of the entitlement to activate.
-     * The name takes the format:
+     * Name uses the format:
      * accounts/{account_id}/customers/{customer_id}/entitlements/{entitlement_id}
      * </pre>
      *
@@ -695,13 +693,12 @@ public Builder setNameBytes(com.google.protobuf.ByteString value) {
      *
      *
      * <pre>
-     * Optional. An optional request ID to identify requests. Specify a unique request ID so
-     * that if you must retry your request, the server will know to ignore the
-     * request if it has already been completed.
-     * For example, consider a situation where you make an initial request and
-     * the request times out. If you make the request again with the same
-     * request ID, the server can check if the original operation with the same
-     * request ID was received, and if so, will ignore the second request.
+     * Optional. You can specify an optional unique request ID, and if you need to retry
+     * your request, the server will know to ignore the request if it's complete.
+     * For example, you make an initial request and the request times out. If you
+     * make the request again with the same request ID, the server can check if
+     * it received the original operation with the same request ID. If it did, it
+     * will ignore the second request.
      * The request ID must be a valid [UUID](https://tools.ietf.org/html/rfc4122)
      * with the exception that zero UUID is not supported
      * (`00000000-0000-0000-0000-000000000000`).
@@ -726,13 +723,12 @@ public java.lang.String getRequestId() {
      *
      *
      * <pre>
-     * Optional. An optional request ID to identify requests. Specify a unique request ID so
-     * that if you must retry your request, the server will know to ignore the
-     * request if it has already been completed.
-     * For example, consider a situation where you make an initial request and
-     * the request times out. If you make the request again with the same
-     * request ID, the server can check if the original operation with the same
-     * request ID was received, and if so, will ignore the second request.
+     * Optional. You can specify an optional unique request ID, and if you need to retry
+     * your request, the server will know to ignore the request if it's complete.
+     * For example, you make an initial request and the request times out. If you
+     * make the request again with the same request ID, the server can check if
+     * it received the original operation with the same request ID. If it did, it
+     * will ignore the second request.
      * The request ID must be a valid [UUID](https://tools.ietf.org/html/rfc4122)
      * with the exception that zero UUID is not supported
      * (`00000000-0000-0000-0000-000000000000`).
@@ -757,13 +753,12 @@ public com.google.protobuf.ByteString getRequestIdBytes() {
      *
      *
      * <pre>
-     * Optional. An optional request ID to identify requests. Specify a unique request ID so
-     * that if you must retry your request, the server will know to ignore the
-     * request if it has already been completed.
-     * For example, consider a situation where you make an initial request and
-     * the request times out. If you make the request again with the same
-     * request ID, the server can check if the original operation with the same
-     * request ID was received, and if so, will ignore the second request.
+     * Optional. You can specify an optional unique request ID, and if you need to retry
+     * your request, the server will know to ignore the request if it's complete.
+     * For example, you make an initial request and the request times out. If you
+     * make the request again with the same request ID, the server can check if
+     * it received the original operation with the same request ID. If it did, it
+     * will ignore the second request.
      * The request ID must be a valid [UUID](https://tools.ietf.org/html/rfc4122)
      * with the exception that zero UUID is not supported
      * (`00000000-0000-0000-0000-000000000000`).
@@ -787,13 +782,12 @@ public Builder setRequestId(java.lang.String value) {
      *
      *
      * <pre>
-     * Optional. An optional request ID to identify requests. Specify a unique request ID so
-     * that if you must retry your request, the server will know to ignore the
-     * request if it has already been completed.
-     * For example, consider a situation where you make an initial request and
-     * the request times out. If you make the request again with the same
-     * request ID, the server can check if the original operation with the same
-     * request ID was received, and if so, will ignore the second request.
+     * Optional. You can specify an optional unique request ID, and if you need to retry
+     * your request, the server will know to ignore the request if it's complete.
+     * For example, you make an initial request and the request times out. If you
+     * make the request again with the same request ID, the server can check if
+     * it received the original operation with the same request ID. If it did, it
+     * will ignore the second request.
      * The request ID must be a valid [UUID](https://tools.ietf.org/html/rfc4122)
      * with the exception that zero UUID is not supported
      * (`00000000-0000-0000-0000-000000000000`).
@@ -813,13 +807,12 @@ public Builder clearRequestId() {
      *
      *
      * <pre>
-     * Optional. An optional request ID to identify requests. Specify a unique request ID so
-     * that if you must retry your request, the server will know to ignore the
-     * request if it has already been completed.
-     * For example, consider a situation where you make an initial request and
-     * the request times out. If you make the request again with the same
-     * request ID, the server can check if the original operation with the same
-     * request ID was received, and if so, will ignore the second request.
+     * Optional. You can specify an optional unique request ID, and if you need to retry
+     * your request, the server will know to ignore the request if it's complete.
+     * For example, you make an initial request and the request times out. If you
+     * make the request again with the same request ID, the server can check if
+     * it received the original operation with the same request ID. If it did, it
+     * will ignore the second request.
      * The request ID must be a valid [UUID](https://tools.ietf.org/html/rfc4122)
      * with the exception that zero UUID is not supported
      * (`00000000-0000-0000-0000-000000000000`).

proto-google-cloud-channel-v1/src/main/java/com/google/cloud/channel/v1/ActivateEntitlementRequestOrBuilder.java

@@ -28,7 +28,7 @@ public interface ActivateEntitlementRequestOrBuilder
    *
    * <pre>
    * Required. The resource name of the entitlement to activate.
-   * The name takes the format:
+   * Name uses the format:
    * accounts/{account_id}/customers/{customer_id}/entitlements/{entitlement_id}
    * </pre>
    *
@@ -42,7 +42,7 @@ public interface ActivateEntitlementRequestOrBuilder
    *
    * <pre>
    * Required. The resource name of the entitlement to activate.
-   * The name takes the format:
+   * Name uses the format:
    * accounts/{account_id}/customers/{customer_id}/entitlements/{entitlement_id}
    * </pre>
    *
@@ -56,13 +56,12 @@ public interface ActivateEntitlementRequestOrBuilder
    *
    *
    * <pre>
-   * Optional. An optional request ID to identify requests. Specify a unique request ID so
-   * that if you must retry your request, the server will know to ignore the
-   * request if it has already been completed.
-   * For example, consider a situation where you make an initial request and
-   * the request times out. If you make the request again with the same
-   * request ID, the server can check if the original operation with the same
-   * request ID was received, and if so, will ignore the second request.
+   * Optional. You can specify an optional unique request ID, and if you need to retry
+   * your request, the server will know to ignore the request if it's complete.
+   * For example, you make an initial request and the request times out. If you
+   * make the request again with the same request ID, the server can check if
+   * it received the original operation with the same request ID. If it did, it
+   * will ignore the second request.
    * The request ID must be a valid [UUID](https://tools.ietf.org/html/rfc4122)
    * with the exception that zero UUID is not supported
    * (`00000000-0000-0000-0000-000000000000`).
@@ -77,13 +76,12 @@ public interface ActivateEntitlementRequestOrBuilder
    *
    *
    * <pre>
-   * Optional. An optional request ID to identify requests. Specify a unique request ID so
-   * that if you must retry your request, the server will know to ignore the
-   * request if it has already been completed.
-   * For example, consider a situation where you make an initial request and
-   * the request times out. If you make the request again with the same
-   * request ID, the server can check if the original operation with the same
-   * request ID was received, and if so, will ignore the second request.
+   * Optional. You can specify an optional unique request ID, and if you need to retry
+   * your request, the server will know to ignore the request if it's complete.
+   * For example, you make an initial request and the request times out. If you
+   * make the request again with the same request ID, the server can check if
+   * it received the original operation with the same request ID. If it did, it
+   * will ignore the second request.
    * The request ID must be a valid [UUID](https://tools.ietf.org/html/rfc4122)
    * with the exception that zero UUID is not supported
    * (`00000000-0000-0000-0000-000000000000`).