googleapis
diff --git a/‎gcloud/datastore/_generated/_datastore.proto‎
Lines changed: 31 additions & 25 deletions b/‎gcloud/datastore/_generated/_datastore.proto‎
Lines changed: 31 additions & 25 deletions
diff --git a/‎gcloud/datastore/_generated/_entity.proto‎
Lines changed: 28 additions & 23 deletions b/‎gcloud/datastore/_generated/_entity.proto‎
Lines changed: 28 additions & 23 deletions
@@ -32,46 +32,47 @@ option java_package = "com.google.datastore.v1beta3";
 // input keys sets the project ID (if not already set) to the project ID from
 // the request.
 //
+//
 service Datastore {
-  // Look up entities by key.
+  // Looks up entities by key.
   rpc Lookup(LookupRequest) returns (LookupResponse) {
     option (google.api.http) = { post: "/v1beta3/projects/{project_id}:lookup" body: "*" };
   }
 
-  // Query for entities.
+  // Queries for entities.
   rpc RunQuery(RunQueryRequest) returns (RunQueryResponse) {
     option (google.api.http) = { post: "/v1beta3/projects/{project_id}:runQuery" body: "*" };
   }
 
-  // Begin a new transaction.
+  // Begins a new transaction.
   rpc BeginTransaction(BeginTransactionRequest) returns (BeginTransactionResponse) {
     option (google.api.http) = { post: "/v1beta3/projects/{project_id}:beginTransaction" body: "*" };
   }
 
-  // Commit a transaction, optionally creating, deleting or modifying some
+  // Commits a transaction, optionally creating, deleting or modifying some
   // entities.
   rpc Commit(CommitRequest) returns (CommitResponse) {
     option (google.api.http) = { post: "/v1beta3/projects/{project_id}:commit" body: "*" };
   }
 
-  // Roll back a transaction.
+  // Rolls back a transaction.
   rpc Rollback(RollbackRequest) returns (RollbackResponse) {
     option (google.api.http) = { post: "/v1beta3/projects/{project_id}:rollback" body: "*" };
   }
 
-  // Allocate IDs for the given keys (useful for referencing an entity before
-  // it is inserted).
+  // Allocates IDs for the given keys, which is useful for referencing an entity
+  // before it is inserted.
   rpc AllocateIds(AllocateIdsRequest) returns (AllocateIdsResponse) {
     option (google.api.http) = { post: "/v1beta3/projects/{project_id}:allocateIds" body: "*" };
   }
 }
 
 // The request for [google.datastore.v1beta3.Datastore.Lookup][google.datastore.v1beta3.Datastore.Lookup].
 message LookupRequest {
-  // Project ID against which to make the request.
+  // The ID of the project against which to make the request.
   string project_id = 8;
 
-  // Options for this lookup request.
+  // The options for this lookup request.
   ReadOptions read_options = 1;
 
   // Keys of entities to look up.
@@ -98,7 +99,7 @@ message LookupResponse {
 
 // The request for [google.datastore.v1beta3.Datastore.RunQuery][google.datastore.v1beta3.Datastore.RunQuery].
 message RunQueryRequest {
-  // Project ID against which to make the request.
+  // The ID of the project against which to make the request.
   string project_id = 8;
 
   // Entities are partitioned into subsets, identified by a partition ID.
@@ -131,7 +132,7 @@ message RunQueryResponse {
 
 // The request for [google.datastore.v1beta3.Datastore.BeginTransaction][google.datastore.v1beta3.Datastore.BeginTransaction].
 message BeginTransactionRequest {
-  // Project ID against which to make the request.
+  // The ID of the project against which to make the request.
   string project_id = 8;
 }
 
@@ -143,7 +144,7 @@ message BeginTransactionResponse {
 
 // The request for [google.datastore.v1beta3.Datastore.Rollback][google.datastore.v1beta3.Datastore.Rollback].
 message RollbackRequest {
-  // Project ID against which to make the request.
+  // The ID of the project against which to make the request.
   string project_id = 8;
 
   // The transaction identifier, returned by a call to
@@ -159,27 +160,30 @@ message RollbackResponse {
 
 // The request for [google.datastore.v1beta3.Datastore.Commit][google.datastore.v1beta3.Datastore.Commit].
 message CommitRequest {
-  // Commit modes.
+  // The modes available for commits.
   enum Mode {
-    // Unspecified.
+    // Unspecified. This value must not be used.
     MODE_UNSPECIFIED = 0;
 
-    // Transactional.
+    // Transactional: The mutations are either all applied, or none are applied.
+    // Learn about transactions [here](https://cloud.google.com/datastore/docs/concepts/transactions).
     TRANSACTIONAL = 1;
 
-    // Non-transactional.
+    // Non-transactional: The mutations may not apply as all or none.
     NON_TRANSACTIONAL = 2;
   }
 
-  // Project ID against which to make the request.
+  // The ID of the project against which to make the request.
   string project_id = 8;
 
   // The type of commit to perform. Defaults to `TRANSACTIONAL`.
   Mode mode = 5;
 
   // Must be set when mode is `TRANSACTIONAL`.
   oneof transaction_selector {
-    // The transaction in which to write.
+    // The identifier of the transaction associated with the commit. A
+    // transaction identifier is returned by a call to
+    // [BeginTransaction][google.datastore.v1beta3.Datastore.BeginTransaction].
     bytes transaction = 1;
   }
 
@@ -188,6 +192,7 @@ message CommitRequest {
   // When mode is `TRANSACTIONAL`, mutations affecting a single entity are
   // applied in order. The following sequences of mutations affecting a single
   // entity are not permitted in a single `Commit` request:
+  //
   // - `insert` followed by `insert`
   // - `update` followed by `insert`
   // - `upsert` followed by `insert`
@@ -204,13 +209,14 @@ message CommitResponse {
   // The i-th mutation result corresponds to the i-th mutation in the request.
   repeated MutationResult mutation_results = 3;
 
-  // The number of index entries updated during the commit.
+  // The number of index entries updated during the commit, or zero if none were
+  // updated.
   int32 index_updates = 4;
 }
 
 // The request for [google.datastore.v1beta3.Datastore.AllocateIds][google.datastore.v1beta3.Datastore.AllocateIds].
 message AllocateIdsRequest {
-  // Project ID against which to make the request.
+  // The ID of the project against which to make the request.
   string project_id = 8;
 
   // A list of keys with incomplete key paths for which to allocate IDs.
@@ -237,15 +243,15 @@ message Mutation {
   //   not even a value in an entity in another value.
   oneof operation {
     // The entity to insert. The entity must not already exist.
-    // The entity's key's final path element may be incomplete.
+    // The entity key's final path element may be incomplete.
     Entity insert = 4;
 
     // The entity to update. The entity must already exist.
     // Must have a complete key path.
     Entity update = 5;
 
     // The entity to upsert. The entity may or may not already exist.
-    // The entity's key's final path element may be incomplete.
+    // The entity key's final path element may be incomplete.
     Entity upsert = 6;
 
     // The key of the entity to delete. The entity may or may not already exist.
@@ -261,11 +267,11 @@ message MutationResult {
   Key key = 3;
 }
 
-// Options shared by read requests.
+// The options shared by read requests.
 message ReadOptions {
-  // Read consistencies.
+  // The possible values for read consistencies.
   enum ReadConsistency {
-    // Unspecified.
+    // Unspecified. This value must not be used.
     READ_CONSISTENCY_UNSPECIFIED = 0;
 
     // Strong consistency.
 
@@ -31,10 +31,12 @@ option java_package = "com.google.datastore.v1beta3";
 //
 // A partition ID contains several dimensions:
 // project ID and namespace ID.
+//
 // Partition dimensions:
-// - A dimension may be `""`.
-// - A dimension must be valid UTF-8 bytes.
-// - A dimension's value must match regex `[A-Za-z\d\.\-_]{1,100}`
+//
+// - May be `""`.
+// - Must be valid UTF-8 bytes.
+// - Must have values that match regex `[A-Za-z\d\.\-_]{1,100}`
 // If the value of any dimension matches regex `__.*__`, the partition is
 // reserved/read-only.
 // A reserved/read-only partition ID is forbidden in certain documented
@@ -44,21 +46,21 @@ option java_package = "com.google.datastore.v1beta3";
 // not match the context project ID ) are discouraged.
 // Reads and writes of foreign partition IDs may fail if the project is not in an active state.
 message PartitionId {
-  // Project ID.
+  // The ID of the project to which the entities belong.
   string project_id = 2;
 
-  // Namespace ID.
+  // If not empty, the ID of the namespace to which the entities belong.
   string namespace_id = 4;
 }
 
 // A unique identifier for an entity.
-// If a key's partition id or any of its path kinds or names are
+// If a key's partition ID or any of its path kinds or names are
 // reserved/read-only, the key is reserved/read-only.
 // A reserved/read-only key is forbidden in certain documented contexts.
 message Key {
   // A (kind, ID/name) pair used to construct a key path.
   //
-  // If either name nor ID is set, the element is complete.
+  // If either name or ID is set, the element is complete.
   // If neither is set, the element is incomplete.
   message PathElement {
     // The kind of the entity.
@@ -67,9 +69,9 @@ message Key {
     // Cannot be `""`.
     string kind = 1;
 
-    // The type of id.
+    // The type of ID.
     oneof id_type {
-      // The auto allocated ID of the entity.
+      // The auto-allocated ID of the entity.
       // Never equal to zero. Values less than zero are discouraged and may not
       // be supported in the future.
       int64 id = 2;
@@ -82,23 +84,27 @@ message Key {
     }
   }
 
-  // Entities are partitioned into subsets, currently identified by a dataset
-  // (usually implicitly specified by the project) and namespace ID.
+  // Entities are partitioned into subsets, currently identified by a project
+  // ID and namespace ID.
   // Queries are scoped to a single partition.
   PartitionId partition_id = 1;
 
   // The entity path.
   // An entity path consists of one or more elements composed of a kind and a
   // string or numerical identifier, which identify entities. The first
   // element identifies a _root entity_, the second element identifies
-  // a _child_ of the root entity, the third element a child of the
+  // a _child_ of the root entity, the third element identifies a child of the
   // second entity, and so forth. The entities identified by all prefixes of
   // the path are called the element's _ancestors_.
+  //
   // An entity path is always fully complete: *all* of the entity's ancestors
   // are required to be in the path along with the entity identifier itself.
   // The only exception is that in some documented cases, the identifier in the
-  // last path element (for the entity) itself may be omitted. A path can never
-  // be empty. The path can have at most 100 elements.
+  // last path element (for the entity) itself may be omitted. For example,
+  // the last path element of the key of `Mutation.insert` may have no
+  // identifier.
+  //
+  // A path can never be empty, and a path can have at most 100 elements.
   repeated PathElement path = 2;
 }
 
@@ -136,10 +142,8 @@ message Value {
     Key key_value = 5;
 
     // A UTF-8 encoded string value.
-    // When `exclude_from_indexes` is false (it is indexed) and meaning is not
-    // 2, may have at most 1500 bytes.
-    // When meaning is 2, may have at most 2083 bytes.
-    // Otherwise, may be set to at least 1,000,000 bytes
+    // When `exclude_from_indexes` is false (it is indexed) , may have at most 1500 bytes.
+    // Otherwise, may be set to at least 1,000,000 bytes.
     string string_value = 17;
 
     // A blob value.
@@ -152,9 +156,10 @@ message Value {
     google.type.LatLng geo_point_value = 8;
 
     // An entity value.
-    // May have no key.
-    // May have a key with an incomplete key path.
-    // May have a reserved/read-only key.
+    //
+    // - May have no key.
+    // - May have a key with an incomplete key path.
+    // - May have a reserved/read-only key.
     Entity entity_value = 6;
 
     // An array value.
@@ -172,7 +177,7 @@ message Value {
   bool exclude_from_indexes = 19;
 }
 
-// An entity.
+// A Datastore data object.
 //
 // An entity is limited to 1 megabyte when stored. That _roughly_
 // corresponds to a limit of 1 megabyte for the serialized form of this
@@ -182,7 +187,7 @@ message Entity {
   //
   // An entity must have a key, unless otherwise documented (for example,
   // an entity in `Value.entity_value` may have no key).
-  // An entity's kind is its key's path's last element's kind,
+  // An entity's kind is its key path's last element's kind,
   // or null if it has no key.
   Key key = 1;