Skip to content

Commit 417c525

Browse files
yoshi-automationyoshi-automation
authored
docs: Add comments to GCS gRPC API proto spec to describe how naming work (#1139)
* docs: Add comments to GCS gRPC API proto spec to describe how naming works PiperOrigin-RevId: 408352508 Source-Author: Google APIs <noreply@google.com> Source-Date: Mon Nov 8 08:42:59 2021 -0800 Source-Repo: googleapis/googleapis Source-Sha: be4be3dde73955e934eb6daddbab68e793e1c1e5 Source-Link: googleapis/googleapis@be4be3d * chore: update Java and Python dependencies PiperOrigin-RevId: 408420890 Source-Author: Google APIs <noreply@google.com> Source-Date: Mon Nov 8 13:03:45 2021 -0800 Source-Repo: googleapis/googleapis Source-Sha: 2921f9fb3bfbd16f6b2da0104373e2b47a80a65e Source-Link: googleapis/googleapis@2921f9f
1 parent af62e23 commit 417c525

File tree

11 files changed

+145
-101
lines changed

11 files changed

+145
-101
lines changed

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

Lines changed: 15 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -29,7 +29,21 @@
2929

3030
// AUTO-GENERATED DOCUMENTATION AND CLASS.
3131
/**
32-
* Service Description: Manages Google Cloud Storage resources.
32+
* Service Description: ## API Overview and Naming Syntax
33+
*
34+
* <p>The GCS gRPC API allows applications to read and write data through the abstractions of
35+
* buckets and objects. For a description of these abstractions please see
36+
* https://cloud.google.com/storage/docs.
37+
*
38+
* <p>Resources are named as follows: - Projects are referred to as they are defined by the Resource
39+
* Manager API, using strings like `projects/123456` or `projects/my-string-id`. - Buckets are named
40+
* using string names of the form: `projects/{project}/buckets/{bucket}` For globally unique
41+
* buckets, `_` may be substituted for the project. - Objects are uniquely identified by their name
42+
* along with the name of the bucket they belong to, as separate strings in this API. For example:
43+
*
44+
* <p>ReadObjectRequest { bucket: 'projects/_/buckets/my-bucket' object: 'my-object' } Note that
45+
* object names can contain `/` characters, which are treated as any other character (no special
46+
* directory semantics).
3347
*
3448
* <p>This class provides the ability to make remote calls to the backing service through method
3549
* 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‎

Lines changed: 15 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -19,7 +19,21 @@
1919
*
2020
* <p>======================= StorageClient =======================
2121
*
22-
* <p>Service Description: Manages Google Cloud Storage resources.
22+
* <p>Service Description: ## API Overview and Naming Syntax
23+
*
24+
* <p>The GCS gRPC API allows applications to read and write data through the abstractions of
25+
* buckets and objects. For a description of these abstractions please see
26+
* https://cloud.google.com/storage/docs.
27+
*
28+
* <p>Resources are named as follows: - Projects are referred to as they are defined by the Resource
29+
* Manager API, using strings like `projects/123456` or `projects/my-string-id`. - Buckets are named
30+
* using string names of the form: `projects/{project}/buckets/{bucket}` For globally unique
31+
* buckets, `_` may be substituted for the project. - Objects are uniquely identified by their name
32+
* along with the name of the bucket they belong to, as separate strings in this API. For example:
33+
*
34+
* <p>ReadObjectRequest { bucket: 'projects/_/buckets/my-bucket' object: 'my-object' } Note that
35+
* object names can contain `/` characters, which are treated as any other character (no special
36+
* directory semantics).
2337
*
2438
* <p>Sample for StorageClient:
2539
*

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

Lines changed: 91 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -21,12 +21,30 @@
2121
*
2222
*
2323
* <pre>
24-
* Manages Google Cloud Storage resources.
24+
* ## API Overview and Naming Syntax
25+
* The GCS gRPC API allows applications to read and write data through the
26+
* abstractions of buckets and objects. For a description of these abstractions
27+
* please see https://cloud.google.com/storage/docs.
28+
* Resources are named as follows:
29+
* - Projects are referred to as they are defined by the Resource Manager API,
30+
* using strings like `projects/123456` or `projects/my-string-id`.
31+
* - Buckets are named using string names of the form:
32+
* `projects/{project}/buckets/{bucket}`
33+
* For globally unique buckets, `_` may be substituted for the project.
34+
* - Objects are uniquely identified by their name along with the name of the
35+
* bucket they belong to, as separate strings in this API. For example:
36+
* ReadObjectRequest {
37+
* bucket: 'projects/_/buckets/my-bucket'
38+
* object: 'my-object'
39+
* }
40+
* Note that object names can contain `/` characters, which are treated as
41+
* any other character (no special directory semantics).
2542
* </pre>
2643
*/
2744
@javax.annotation.Generated(
2845
value = "by gRPC proto compiler",
2946
comments = "Source: google/storage/v2/storage.proto")
47+
@io.grpc.stub.annotations.GrpcGenerated
3048
public final class StorageGrpc {
3149

3250
private StorageGrpc() {}
@@ -252,7 +270,24 @@ public StorageFutureStub newStub(
252270
*
253271
*
254272
* <pre>
255-
* Manages Google Cloud Storage resources.
273+
* ## API Overview and Naming Syntax
274+
* The GCS gRPC API allows applications to read and write data through the
275+
* abstractions of buckets and objects. For a description of these abstractions
276+
* please see https://cloud.google.com/storage/docs.
277+
* Resources are named as follows:
278+
* - Projects are referred to as they are defined by the Resource Manager API,
279+
* using strings like `projects/123456` or `projects/my-string-id`.
280+
* - Buckets are named using string names of the form:
281+
* `projects/{project}/buckets/{bucket}`
282+
* For globally unique buckets, `_` may be substituted for the project.
283+
* - Objects are uniquely identified by their name along with the name of the
284+
* bucket they belong to, as separate strings in this API. For example:
285+
* ReadObjectRequest {
286+
* bucket: 'projects/_/buckets/my-bucket'
287+
* object: 'my-object'
288+
* }
289+
* Note that object names can contain `/` characters, which are treated as
290+
* any other character (no special directory semantics).
256291
* </pre>
257292
*/
258293
public abstract static class StorageImplBase implements io.grpc.BindableService {
@@ -382,7 +417,24 @@ public final io.grpc.ServerServiceDefinition bindService() {
382417
*
383418
*
384419
* <pre>
385-
* Manages Google Cloud Storage resources.
420+
* ## API Overview and Naming Syntax
421+
* The GCS gRPC API allows applications to read and write data through the
422+
* abstractions of buckets and objects. For a description of these abstractions
423+
* please see https://cloud.google.com/storage/docs.
424+
* Resources are named as follows:
425+
* - Projects are referred to as they are defined by the Resource Manager API,
426+
* using strings like `projects/123456` or `projects/my-string-id`.
427+
* - Buckets are named using string names of the form:
428+
* `projects/{project}/buckets/{bucket}`
429+
* For globally unique buckets, `_` may be substituted for the project.
430+
* - Objects are uniquely identified by their name along with the name of the
431+
* bucket they belong to, as separate strings in this API. For example:
432+
* ReadObjectRequest {
433+
* bucket: 'projects/_/buckets/my-bucket'
434+
* object: 'my-object'
435+
* }
436+
* Note that object names can contain `/` characters, which are treated as
437+
* any other character (no special directory semantics).
386438
* </pre>
387439
*/
388440
public static final class StorageStub extends io.grpc.stub.AbstractAsyncStub<StorageStub> {
@@ -493,7 +545,24 @@ public void queryWriteStatus(
493545
*
494546
*
495547
* <pre>
496-
* Manages Google Cloud Storage resources.
548+
* ## API Overview and Naming Syntax
549+
* The GCS gRPC API allows applications to read and write data through the
550+
* abstractions of buckets and objects. For a description of these abstractions
551+
* please see https://cloud.google.com/storage/docs.
552+
* Resources are named as follows:
553+
* - Projects are referred to as they are defined by the Resource Manager API,
554+
* using strings like `projects/123456` or `projects/my-string-id`.
555+
* - Buckets are named using string names of the form:
556+
* `projects/{project}/buckets/{bucket}`
557+
* For globally unique buckets, `_` may be substituted for the project.
558+
* - Objects are uniquely identified by their name along with the name of the
559+
* bucket they belong to, as separate strings in this API. For example:
560+
* ReadObjectRequest {
561+
* bucket: 'projects/_/buckets/my-bucket'
562+
* object: 'my-object'
563+
* }
564+
* Note that object names can contain `/` characters, which are treated as
565+
* any other character (no special directory semantics).
497566
* </pre>
498567
*/
499568
public static final class StorageBlockingStub
@@ -563,7 +632,24 @@ public com.google.storage.v2.QueryWriteStatusResponse queryWriteStatus(
563632
*
564633
*
565634
* <pre>
566-
* Manages Google Cloud Storage resources.
635+
* ## API Overview and Naming Syntax
636+
* The GCS gRPC API allows applications to read and write data through the
637+
* abstractions of buckets and objects. For a description of these abstractions
638+
* please see https://cloud.google.com/storage/docs.
639+
* Resources are named as follows:
640+
* - Projects are referred to as they are defined by the Resource Manager API,
641+
* using strings like `projects/123456` or `projects/my-string-id`.
642+
* - Buckets are named using string names of the form:
643+
* `projects/{project}/buckets/{bucket}`
644+
* For globally unique buckets, `_` may be substituted for the project.
645+
* - Objects are uniquely identified by their name along with the name of the
646+
* bucket they belong to, as separate strings in this API. For example:
647+
* ReadObjectRequest {
648+
* bucket: 'projects/_/buckets/my-bucket'
649+
* object: 'my-object'
650+
* }
651+
* Note that object names can contain `/` characters, which are treated as
652+
* any other character (no special directory semantics).
567653
* </pre>
568654
*/
569655
public static final class StorageFutureStub

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

Lines changed: 0 additions & 49 deletions
Original file line numberDiff line numberDiff line change
@@ -14384,11 +14384,6 @@ public com.google.storage.v2.Bucket.Website getDefaultInstanceForType() {
1438414384
*
1438514385
* <pre>
1438614386
* Immutable. The name of the bucket.
14387-
* Global buckets will be of the format `projects/{project}/buckets/{bucket}`.
14388-
* Other sorts of buckets in the future are not guaranteed to follow this
14389-
* pattern.
14390-
* For globally unique bucket names, a `_` may be substituted for the project
14391-
* ID.
1439214387
* </pre>
1439314388
*
1439414389
* <code>string name = 1 [(.google.api.field_behavior) = IMMUTABLE];</code>
@@ -14412,11 +14407,6 @@ public java.lang.String getName() {
1441214407
*
1441314408
* <pre>
1441414409
* Immutable. The name of the bucket.
14415-
* Global buckets will be of the format `projects/{project}/buckets/{bucket}`.
14416-
* Other sorts of buckets in the future are not guaranteed to follow this
14417-
* pattern.
14418-
* For globally unique bucket names, a `_` may be substituted for the project
14419-
* ID.
1442014410
* </pre>
1442114411
*
1442214412
* <code>string name = 1 [(.google.api.field_behavior) = IMMUTABLE];</code>
@@ -14496,8 +14486,6 @@ public com.google.protobuf.ByteString getBucketIdBytes() {
1449614486
*
1449714487
* <pre>
1449814488
* Immutable. The project which owns this bucket.
14499-
* Format: projects/{project_number}
14500-
* Example: `projects/123456`.
1450114489
* </pre>
1450214490
*
1450314491
* <code>
@@ -14523,8 +14511,6 @@ public java.lang.String getProject() {
1452314511
*
1452414512
* <pre>
1452514513
* Immutable. The project which owns this bucket.
14526-
* Format: projects/{project_number}
14527-
* Example: `projects/123456`.
1452814514
* </pre>
1452914515
*
1453014516
* <code>
@@ -16767,11 +16753,6 @@ public Builder mergeFrom(
1676716753
*
1676816754
* <pre>
1676916755
* Immutable. The name of the bucket.
16770-
* Global buckets will be of the format `projects/{project}/buckets/{bucket}`.
16771-
* Other sorts of buckets in the future are not guaranteed to follow this
16772-
* pattern.
16773-
* For globally unique bucket names, a `_` may be substituted for the project
16774-
* ID.
1677516756
* </pre>
1677616757
*
1677716758
* <code>string name = 1 [(.google.api.field_behavior) = IMMUTABLE];</code>
@@ -16794,11 +16775,6 @@ public java.lang.String getName() {
1679416775
*
1679516776
* <pre>
1679616777
* Immutable. The name of the bucket.
16797-
* Global buckets will be of the format `projects/{project}/buckets/{bucket}`.
16798-
* Other sorts of buckets in the future are not guaranteed to follow this
16799-
* pattern.
16800-
* For globally unique bucket names, a `_` may be substituted for the project
16801-
* ID.
1680216778
* </pre>
1680316779
*
1680416780
* <code>string name = 1 [(.google.api.field_behavior) = IMMUTABLE];</code>
@@ -16821,11 +16797,6 @@ public com.google.protobuf.ByteString getNameBytes() {
1682116797
*
1682216798
* <pre>
1682316799
* Immutable. The name of the bucket.
16824-
* Global buckets will be of the format `projects/{project}/buckets/{bucket}`.
16825-
* Other sorts of buckets in the future are not guaranteed to follow this
16826-
* pattern.
16827-
* For globally unique bucket names, a `_` may be substituted for the project
16828-
* ID.
1682916800
* </pre>
1683016801
*
1683116802
* <code>string name = 1 [(.google.api.field_behavior) = IMMUTABLE];</code>
@@ -16847,11 +16818,6 @@ public Builder setName(java.lang.String value) {
1684716818
*
1684816819
* <pre>
1684916820
* Immutable. The name of the bucket.
16850-
* Global buckets will be of the format `projects/{project}/buckets/{bucket}`.
16851-
* Other sorts of buckets in the future are not guaranteed to follow this
16852-
* pattern.
16853-
* For globally unique bucket names, a `_` may be substituted for the project
16854-
* ID.
1685516821
* </pre>
1685616822
*
1685716823
* <code>string name = 1 [(.google.api.field_behavior) = IMMUTABLE];</code>
@@ -16869,11 +16835,6 @@ public Builder clearName() {
1686916835
*
1687016836
* <pre>
1687116837
* Immutable. The name of the bucket.
16872-
* Global buckets will be of the format `projects/{project}/buckets/{bucket}`.
16873-
* Other sorts of buckets in the future are not guaranteed to follow this
16874-
* pattern.
16875-
* For globally unique bucket names, a `_` may be substituted for the project
16876-
* ID.
1687716838
* </pre>
1687816839
*
1687916840
* <code>string name = 1 [(.google.api.field_behavior) = IMMUTABLE];</code>
@@ -17014,8 +16975,6 @@ public Builder setBucketIdBytes(com.google.protobuf.ByteString value) {
1701416975
*
1701516976
* <pre>
1701616977
* Immutable. The project which owns this bucket.
17017-
* Format: projects/{project_number}
17018-
* Example: `projects/123456`.
1701916978
* </pre>
1702016979
*
1702116980
* <code>
@@ -17040,8 +16999,6 @@ public java.lang.String getProject() {
1704016999
*
1704117000
* <pre>
1704217001
* Immutable. The project which owns this bucket.
17043-
* Format: projects/{project_number}
17044-
* Example: `projects/123456`.
1704517002
* </pre>
1704617003
*
1704717004
* <code>
@@ -17066,8 +17023,6 @@ public com.google.protobuf.ByteString getProjectBytes() {
1706617023
*
1706717024
* <pre>
1706817025
* Immutable. The project which owns this bucket.
17069-
* Format: projects/{project_number}
17070-
* Example: `projects/123456`.
1707117026
* </pre>
1707217027
*
1707317028
* <code>
@@ -17091,8 +17046,6 @@ public Builder setProject(java.lang.String value) {
1709117046
*
1709217047
* <pre>
1709317048
* Immutable. The project which owns this bucket.
17094-
* Format: projects/{project_number}
17095-
* Example: `projects/123456`.
1709617049
* </pre>
1709717050
*
1709817051
* <code>
@@ -17112,8 +17065,6 @@ public Builder clearProject() {
1711217065
*
1711317066
* <pre>
1711417067
* Immutable. The project which owns this bucket.
17115-
* Format: projects/{project_number}
17116-
* Example: `projects/123456`.
1711717068
* </pre>
1711817069
*
1711917070
* <code>

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

Lines changed: 0 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -28,11 +28,6 @@ public interface BucketOrBuilder
2828
*
2929
* <pre>
3030
* Immutable. The name of the bucket.
31-
* Global buckets will be of the format `projects/{project}/buckets/{bucket}`.
32-
* Other sorts of buckets in the future are not guaranteed to follow this
33-
* pattern.
34-
* For globally unique bucket names, a `_` may be substituted for the project
35-
* ID.
3631
* </pre>
3732
*
3833
* <code>string name = 1 [(.google.api.field_behavior) = IMMUTABLE];</code>
@@ -45,11 +40,6 @@ public interface BucketOrBuilder
4540
*
4641
* <pre>
4742
* Immutable. The name of the bucket.
48-
* Global buckets will be of the format `projects/{project}/buckets/{bucket}`.
49-
* Other sorts of buckets in the future are not guaranteed to follow this
50-
* pattern.
51-
* For globally unique bucket names, a `_` may be substituted for the project
52-
* ID.
5343
* </pre>
5444
*
5545
* <code>string name = 1 [(.google.api.field_behavior) = IMMUTABLE];</code>
@@ -92,8 +82,6 @@ public interface BucketOrBuilder
9282
*
9383
* <pre>
9484
* Immutable. The project which owns this bucket.
95-
* Format: projects/{project_number}
96-
* Example: `projects/123456`.
9785
* </pre>
9886
*
9987
* <code>
@@ -108,8 +96,6 @@ public interface BucketOrBuilder
10896
*
10997
* <pre>
11098
* Immutable. The project which owns this bucket.
111-
* Format: projects/{project_number}
112-
* Example: `projects/123456`.
11399
* </pre>
114100
*
115101
* <code>

0 commit comments

Comments
 (0)