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

Google APIs · copybara-github · commit be4be3dde739 · 2021-11-08T08:43:36.000-08:00
PiperOrigin-RevId: 408352508
diff --git a/google/storage/v2/storage.proto b/google/storage/v2/storage.proto
@@ -35,7 +35,27 @@ option (google.api.resource_definition) = {
   pattern: "projects/{project}/locations/{location}/keyRings/{key_ring}/cryptoKeys/{crypto_key}"
 };
 
-// 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).
 service Storage {
   option (google.api.default_host) = "storage.googleapis.com";
   option (google.api.oauth_scopes) =
@@ -353,7 +373,6 @@ message CommonObjectRequestParams {
 // Parameters that can be passed to any request.
 message CommonRequestParams {
   // Required. Required when using buckets with Requestor Pays feature enabled.
-  // Example: `projects/123456`.
   string user_project = 1 [
     (google.api.field_behavior) = REQUIRED,
     (google.api.resource_reference) = {
@@ -664,11 +683,6 @@ message Bucket {
   }
 
   // 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.
   string name = 1 [(google.api.field_behavior) = IMMUTABLE];
 
   // Output only. The user-chosen part of the bucket name. The `{bucket}` portion of the
@@ -677,8 +691,6 @@ message Bucket {
   string bucket_id = 2 [(google.api.field_behavior) = OUTPUT_ONLY];
 
   // Immutable. The project which owns this bucket.
-  // Format: projects/{project_number}
-  // Example: `projects/123456`.
   string project = 3 [
     (google.api.field_behavior) = IMMUTABLE,
     (google.api.resource_reference) = {
@@ -895,7 +907,6 @@ message Object {
   string name = 1 [(google.api.field_behavior) = IMMUTABLE];
 
   // Immutable. The name of the bucket containing this object.
-  // Example: `projects/_/buckets/foo`.
   string bucket = 2 [
     (google.api.field_behavior) = IMMUTABLE,
     (google.api.resource_reference) = {
