docs: Add comments to GCS gRPC API proto spec to describe how naming work

gapic-google-cloud-storage-v2/src/main/java/com/google/storage/v2/StorageClient.java

@@ -29,7 +29,21 @@
 
 // AUTO-GENERATED DOCUMENTATION AND CLASS.
 /**
- * Service Description: Manages Google Cloud Storage resources.
+ * Service Description: ## API Overview and Naming Syntax
+ *
+ * <p>The GCS gRPC API allows applications to read and write data through the abstractions of
+ * buckets and objects. For a description of these abstractions please see
+ * https://cloud.google.com/storage/docs.
+ *
+ * <p>Resources are named as follows: - Projects are referred to as they are defined by the Resource
+ * Manager API, using strings like `projects/123456` or `projects/my-string-id`. - Buckets are named
+ * using string names of the form: `projects/{project}/buckets/{bucket}` For globally unique
+ * buckets, `_` may be substituted for the project. - Objects are uniquely identified by their name
+ * along with the name of the bucket they belong to, as separate strings in this API. For example:
+ *
+ * <p>ReadObjectRequest { bucket: 'projects/_/buckets/my-bucket' object: 'my-object' } Note that
+ * object names can contain `/` characters, which are treated as any other character (no special
+ * directory semantics).
  *
  * <p>This class provides the ability to make remote calls to the backing service through method
  * calls that map to API methods. Sample code to get started:

gapic-google-cloud-storage-v2/src/main/java/com/google/storage/v2/package-info.java

@@ -19,7 +19,21 @@
  *
  * <p>======================= StorageClient =======================
  *
- * <p>Service Description: Manages Google Cloud Storage resources.
+ * <p>Service Description: ## API Overview and Naming Syntax
+ *
+ * <p>The GCS gRPC API allows applications to read and write data through the abstractions of
+ * buckets and objects. For a description of these abstractions please see
+ * https://cloud.google.com/storage/docs.
+ *
+ * <p>Resources are named as follows: - Projects are referred to as they are defined by the Resource
+ * Manager API, using strings like `projects/123456` or `projects/my-string-id`. - Buckets are named
+ * using string names of the form: `projects/{project}/buckets/{bucket}` For globally unique
+ * buckets, `_` may be substituted for the project. - Objects are uniquely identified by their name
+ * along with the name of the bucket they belong to, as separate strings in this API. For example:
+ *
+ * <p>ReadObjectRequest { bucket: 'projects/_/buckets/my-bucket' object: 'my-object' } Note that
+ * object names can contain `/` characters, which are treated as any other character (no special
+ * directory semantics).
  *
  * <p>Sample for StorageClient:
  *

grpc-google-cloud-storage-v2/src/main/java/com/google/storage/v2/StorageGrpc.java

@@ -21,12 +21,30 @@
  *
  *
  * <pre>
- * Manages Google Cloud Storage resources.
+ * ## API Overview and Naming Syntax
+ * The GCS gRPC API allows applications to read and write data through the
+ * abstractions of buckets and objects. For a description of these abstractions
+ * please see https://cloud.google.com/storage/docs.
+ * Resources are named as follows:
+ *   - Projects are referred to as they are defined by the Resource Manager API,
+ *     using strings like `projects/123456` or `projects/my-string-id`.
+ *   - Buckets are named using string names of the form:
+ *     `projects/{project}/buckets/{bucket}`
+ *     For globally unique buckets, `_` may be substituted for the project.
+ *   - Objects are uniquely identified by their name along with the name of the
+ *     bucket they belong to, as separate strings in this API. For example:
+ *       ReadObjectRequest {
+ *         bucket: 'projects/_/buckets/my-bucket'
+ *         object: 'my-object'
+ *       }
+ *     Note that object names can contain `/` characters, which are treated as
+ *     any other character (no special directory semantics).
  * </pre>
  */
 @javax.annotation.Generated(
     value = "by gRPC proto compiler",
     comments = "Source: google/storage/v2/storage.proto")
+@io.grpc.stub.annotations.GrpcGenerated
 public final class StorageGrpc {
 
   private StorageGrpc() {}
@@ -252,7 +270,24 @@ public StorageFutureStub newStub(
    *
    *
    * <pre>
-   * Manages Google Cloud Storage resources.
+   * ## API Overview and Naming Syntax
+   * The GCS gRPC API allows applications to read and write data through the
+   * abstractions of buckets and objects. For a description of these abstractions
+   * please see https://cloud.google.com/storage/docs.
+   * Resources are named as follows:
+   *   - Projects are referred to as they are defined by the Resource Manager API,
+   *     using strings like `projects/123456` or `projects/my-string-id`.
+   *   - Buckets are named using string names of the form:
+   *     `projects/{project}/buckets/{bucket}`
+   *     For globally unique buckets, `_` may be substituted for the project.
+   *   - Objects are uniquely identified by their name along with the name of the
+   *     bucket they belong to, as separate strings in this API. For example:
+   *       ReadObjectRequest {
+   *         bucket: 'projects/_/buckets/my-bucket'
+   *         object: 'my-object'
+   *       }
+   *     Note that object names can contain `/` characters, which are treated as
+   *     any other character (no special directory semantics).
    * </pre>
    */
   public abstract static class StorageImplBase implements io.grpc.BindableService {
@@ -382,7 +417,24 @@ public final io.grpc.ServerServiceDefinition bindService() {
    *
    *
    * <pre>
-   * Manages Google Cloud Storage resources.
+   * ## API Overview and Naming Syntax
+   * The GCS gRPC API allows applications to read and write data through the
+   * abstractions of buckets and objects. For a description of these abstractions
+   * please see https://cloud.google.com/storage/docs.
+   * Resources are named as follows:
+   *   - Projects are referred to as they are defined by the Resource Manager API,
+   *     using strings like `projects/123456` or `projects/my-string-id`.
+   *   - Buckets are named using string names of the form:
+   *     `projects/{project}/buckets/{bucket}`
+   *     For globally unique buckets, `_` may be substituted for the project.
+   *   - Objects are uniquely identified by their name along with the name of the
+   *     bucket they belong to, as separate strings in this API. For example:
+   *       ReadObjectRequest {
+   *         bucket: 'projects/_/buckets/my-bucket'
+   *         object: 'my-object'
+   *       }
+   *     Note that object names can contain `/` characters, which are treated as
+   *     any other character (no special directory semantics).
    * </pre>
    */
   public static final class StorageStub extends io.grpc.stub.AbstractAsyncStub<StorageStub> {
@@ -493,7 +545,24 @@ public void queryWriteStatus(
    *
    *
    * <pre>
-   * Manages Google Cloud Storage resources.
+   * ## API Overview and Naming Syntax
+   * The GCS gRPC API allows applications to read and write data through the
+   * abstractions of buckets and objects. For a description of these abstractions
+   * please see https://cloud.google.com/storage/docs.
+   * Resources are named as follows:
+   *   - Projects are referred to as they are defined by the Resource Manager API,
+   *     using strings like `projects/123456` or `projects/my-string-id`.
+   *   - Buckets are named using string names of the form:
+   *     `projects/{project}/buckets/{bucket}`
+   *     For globally unique buckets, `_` may be substituted for the project.
+   *   - Objects are uniquely identified by their name along with the name of the
+   *     bucket they belong to, as separate strings in this API. For example:
+   *       ReadObjectRequest {
+   *         bucket: 'projects/_/buckets/my-bucket'
+   *         object: 'my-object'
+   *       }
+   *     Note that object names can contain `/` characters, which are treated as
+   *     any other character (no special directory semantics).
    * </pre>
    */
   public static final class StorageBlockingStub
@@ -563,7 +632,24 @@ public com.google.storage.v2.QueryWriteStatusResponse queryWriteStatus(
    *
    *
    * <pre>
-   * Manages Google Cloud Storage resources.
+   * ## API Overview and Naming Syntax
+   * The GCS gRPC API allows applications to read and write data through the
+   * abstractions of buckets and objects. For a description of these abstractions
+   * please see https://cloud.google.com/storage/docs.
+   * Resources are named as follows:
+   *   - Projects are referred to as they are defined by the Resource Manager API,
+   *     using strings like `projects/123456` or `projects/my-string-id`.
+   *   - Buckets are named using string names of the form:
+   *     `projects/{project}/buckets/{bucket}`
+   *     For globally unique buckets, `_` may be substituted for the project.
+   *   - Objects are uniquely identified by their name along with the name of the
+   *     bucket they belong to, as separate strings in this API. For example:
+   *       ReadObjectRequest {
+   *         bucket: 'projects/_/buckets/my-bucket'
+   *         object: 'my-object'
+   *       }
+   *     Note that object names can contain `/` characters, which are treated as
+   *     any other character (no special directory semantics).
    * </pre>
    */
   public static final class StorageFutureStub

proto-google-cloud-storage-v2/src/main/java/com/google/storage/v2/Bucket.java

@@ -14384,11 +14384,6 @@ public com.google.storage.v2.Bucket.Website getDefaultInstanceForType() {
    *
    * <pre>
    * Immutable. The name of the bucket.
-   * Global buckets will be of the format `projects/{project}/buckets/{bucket}`.
-   * Other sorts of buckets in the future are not guaranteed to follow this
-   * pattern.
-   * For globally unique bucket names, a `_` may be substituted for the project
-   * ID.
    * </pre>
    *
    * <code>string name = 1 [(.google.api.field_behavior) = IMMUTABLE];</code>
@@ -14412,11 +14407,6 @@ public java.lang.String getName() {
    *
    * <pre>
    * Immutable. The name of the bucket.
-   * Global buckets will be of the format `projects/{project}/buckets/{bucket}`.
-   * Other sorts of buckets in the future are not guaranteed to follow this
-   * pattern.
-   * For globally unique bucket names, a `_` may be substituted for the project
-   * ID.
    * </pre>
    *
    * <code>string name = 1 [(.google.api.field_behavior) = IMMUTABLE];</code>
@@ -14496,8 +14486,6 @@ public com.google.protobuf.ByteString getBucketIdBytes() {
    *
    * <pre>
    * Immutable. The project which owns this bucket.
-   * Format: projects/{project_number}
-   * Example: `projects/123456`.
    * </pre>
    *
    * <code>
@@ -14523,8 +14511,6 @@ public java.lang.String getProject() {
    *
    * <pre>
    * Immutable. The project which owns this bucket.
-   * Format: projects/{project_number}
-   * Example: `projects/123456`.
    * </pre>
    *
    * <code>
@@ -16767,11 +16753,6 @@ public Builder mergeFrom(
      *
      * <pre>
      * Immutable. The name of the bucket.
-     * Global buckets will be of the format `projects/{project}/buckets/{bucket}`.
-     * Other sorts of buckets in the future are not guaranteed to follow this
-     * pattern.
-     * For globally unique bucket names, a `_` may be substituted for the project
-     * ID.
      * </pre>
      *
      * <code>string name = 1 [(.google.api.field_behavior) = IMMUTABLE];</code>
@@ -16794,11 +16775,6 @@ public java.lang.String getName() {
      *
      * <pre>
      * Immutable. The name of the bucket.
-     * Global buckets will be of the format `projects/{project}/buckets/{bucket}`.
-     * Other sorts of buckets in the future are not guaranteed to follow this
-     * pattern.
-     * For globally unique bucket names, a `_` may be substituted for the project
-     * ID.
      * </pre>
      *
      * <code>string name = 1 [(.google.api.field_behavior) = IMMUTABLE];</code>
@@ -16821,11 +16797,6 @@ public com.google.protobuf.ByteString getNameBytes() {
      *
      * <pre>
      * Immutable. The name of the bucket.
-     * Global buckets will be of the format `projects/{project}/buckets/{bucket}`.
-     * Other sorts of buckets in the future are not guaranteed to follow this
-     * pattern.
-     * For globally unique bucket names, a `_` may be substituted for the project
-     * ID.
      * </pre>
      *
      * <code>string name = 1 [(.google.api.field_behavior) = IMMUTABLE];</code>
@@ -16847,11 +16818,6 @@ public Builder setName(java.lang.String value) {
      *
      * <pre>
      * Immutable. The name of the bucket.
-     * Global buckets will be of the format `projects/{project}/buckets/{bucket}`.
-     * Other sorts of buckets in the future are not guaranteed to follow this
-     * pattern.
-     * For globally unique bucket names, a `_` may be substituted for the project
-     * ID.
      * </pre>
      *
      * <code>string name = 1 [(.google.api.field_behavior) = IMMUTABLE];</code>
@@ -16869,11 +16835,6 @@ public Builder clearName() {
      *
      * <pre>
      * Immutable. The name of the bucket.
-     * Global buckets will be of the format `projects/{project}/buckets/{bucket}`.
-     * Other sorts of buckets in the future are not guaranteed to follow this
-     * pattern.
-     * For globally unique bucket names, a `_` may be substituted for the project
-     * ID.
      * </pre>
      *
      * <code>string name = 1 [(.google.api.field_behavior) = IMMUTABLE];</code>
@@ -17014,8 +16975,6 @@ public Builder setBucketIdBytes(com.google.protobuf.ByteString value) {
      *
      * <pre>
      * Immutable. The project which owns this bucket.
-     * Format: projects/{project_number}
-     * Example: `projects/123456`.
      * </pre>
      *
      * <code>
@@ -17040,8 +16999,6 @@ public java.lang.String getProject() {
      *
      * <pre>
      * Immutable. The project which owns this bucket.
-     * Format: projects/{project_number}
-     * Example: `projects/123456`.
      * </pre>
      *
      * <code>
@@ -17066,8 +17023,6 @@ public com.google.protobuf.ByteString getProjectBytes() {
      *
      * <pre>
      * Immutable. The project which owns this bucket.
-     * Format: projects/{project_number}
-     * Example: `projects/123456`.
      * </pre>
      *
      * <code>
@@ -17091,8 +17046,6 @@ public Builder setProject(java.lang.String value) {
      *
      * <pre>
      * Immutable. The project which owns this bucket.
-     * Format: projects/{project_number}
-     * Example: `projects/123456`.
      * </pre>
      *
      * <code>
@@ -17112,8 +17065,6 @@ public Builder clearProject() {
      *
      * <pre>
      * Immutable. The project which owns this bucket.
-     * Format: projects/{project_number}
-     * Example: `projects/123456`.
      * </pre>
      *
      * <code>

proto-google-cloud-storage-v2/src/main/java/com/google/storage/v2/BucketOrBuilder.java

@@ -28,11 +28,6 @@ public interface BucketOrBuilder
    *
    * <pre>
    * Immutable. The name of the bucket.
-   * Global buckets will be of the format `projects/{project}/buckets/{bucket}`.
-   * Other sorts of buckets in the future are not guaranteed to follow this
-   * pattern.
-   * For globally unique bucket names, a `_` may be substituted for the project
-   * ID.
    * </pre>
    *
    * <code>string name = 1 [(.google.api.field_behavior) = IMMUTABLE];</code>
@@ -45,11 +40,6 @@ public interface BucketOrBuilder
    *
    * <pre>
    * Immutable. The name of the bucket.
-   * Global buckets will be of the format `projects/{project}/buckets/{bucket}`.
-   * Other sorts of buckets in the future are not guaranteed to follow this
-   * pattern.
-   * For globally unique bucket names, a `_` may be substituted for the project
-   * ID.
    * </pre>
    *
    * <code>string name = 1 [(.google.api.field_behavior) = IMMUTABLE];</code>
@@ -92,8 +82,6 @@ public interface BucketOrBuilder
    *
    * <pre>
    * Immutable. The project which owns this bucket.
-   * Format: projects/{project_number}
-   * Example: `projects/123456`.
    * </pre>
    *
    * <code>
@@ -108,8 +96,6 @@ public interface BucketOrBuilder
    *
    * <pre>
    * Immutable. The project which owns this bucket.
-   * Format: projects/{project_number}
-   * Example: `projects/123456`.
    * </pre>
    *
    * <code>