Consistently add ticks around identifiers

Author: G8XSU

app/src/main/proto/vss.proto

@@ -6,79 +6,79 @@ option java_package = "org.vss";
 // Request payload to be used for `GetObject` API call to server.
 message GetObjectRequest {
 
-  // store_id is a keyspace identifier.
+  // `store_id` is a keyspace identifier.
   // Ref: https://en.wikipedia.org/wiki/Keyspace_(distributed_data_store)
-  // All APIs operate within a single store_id.
+  // All APIs operate within a single `store_id`.
   // It is up to clients to use single or multiple stores for their use-case.
   // This can be used for client-isolation/ rate-limiting / throttling on the server-side.
-  // Authorization and billing can also be performed at the store_id level.
+  // Authorization and billing can also be performed at the `store_id` level.
   string store_id = 1;
 
-  // Key for which the value is to be fetched.
+  // `Key` for which the value is to be fetched.
   //
   // Consistency Guarantee:
-  // Get(read) operations against a key are consistent reads and will reflect all previous writes,
+  // Get(read) operations against a `key` are consistent reads and will reflect all previous writes,
   // since Put/Write provides read-after-write and read-after-update consistency guarantees.
   //
   // Read Isolation:
-  // Get/Read operations against a key are ensured to have read-committed isolation.
+  // Get/Read operations against a `key` are ensured to have read-committed isolation.
   // Ref: https://en.wikipedia.org/wiki/Isolation_(database_systems)#Read_committed
   string key = 2;
 }
 
 // Server response for `GetObject` API.
 message GetObjectResponse {
 
-  // Fetched value and version along with the corresponding key in the request.
+  // Fetched `value` and `version` along with the corresponding `key` in the request.
   KeyValue value = 2;
 }
 
 // Request payload to be used for `PutObject` API call to server.
 message PutObjectRequest {
 
-  // store_id is a keyspace identifier.
+  // `store_id` is a keyspace identifier.
   // Ref: https://en.wikipedia.org/wiki/Keyspace_(distributed_data_store)
-  // All APIs operate within a single store_id.
+  // All APIs operate within a single `store_id`.
   // It is up to clients to use single or multiple stores for their use-case.
   // This can be used for client-isolation/ rate-limiting / throttling on the server-side.
-  // Authorization and billing can also be performed at the store_id level.
+  // Authorization and billing can also be performed at the `store_id` level.
   string store_id = 1;
 
-  // global_version is a sequence-number/version of the whole store. This can be used for versioning
+  // `global_version` is a sequence-number/version of the whole store. This can be used for versioning
   // and ensures that multiple updates in case of multiple devices can only be done linearly, even
-  // if those updates did not directly conflict with each other based on keys/transaction_items.
+  // if those updates did not directly conflict with each other based on keys/`transaction_items`.
   //
-  // If present, the write will only succeed if the current server-side global_version against
-  // the store_id is same as in the request.
-  // Clients are expected to store (client-side) the global version against store_id.
-  // The request must contain their client-side value of global_version if global versioning and
+  // If present, the write will only succeed if the current server-side `global_version` against
+  // the `store_id` is same as in the request.
+  // Clients are expected to store (client-side) the global version against `store_id`.
+  // The request must contain their client-side value of `global_version` if global versioning and
   // conflict detection is desired.
   //
   // For the first write of the store, global version should be '0'. If the write succeeds, clients
   // must increment their global version (client-side) by 1.
-  // The server increments global_version (server-side) for every successful write, hence this
+  // The server increments `global_version` (server-side) for every successful write, hence this
   // client-side increment is required to ensure matching versions. This updated global version
   // should be used in subsequent PutObjectRequests for the store.
   //
   // Requests with a conflicting version will fail with `CONFLICT_EXCEPTION` as ErrorCode.
   optional int64 global_version = 2;
 
-  // Items to be written as a result of this PutObjectRequest.
+  // Items to be written as a result of this `PutObjectRequest`.
   //
-  // In an item, each key is supplied with its corresponding value and version.
+  // In an item, each `key` is supplied with its corresponding `value` and `version`.
   // Clients can choose to encrypt the keys client-side in order to obfuscate their usage patterns.
-  // If the write is successful, the previous value corresponding to the key will be overwritten.
+  // If the write is successful, the previous `value` corresponding to the `key` will be overwritten.
   //
-  // Multiple items in transaction_items and delete_items of a single PutObjectRequest are written in
+  // Multiple items in `transaction_items` and `delete_items` of a single `PutObjectRequest` are written in
   // a database-transaction in an all-or-nothing fashion.
-  // All Items in a single PutObjectRequest must have distinct keys.
+  // All Items in a single `PutObjectRequest` must have distinct keys.
   //
-  // Clients are expected to store a version against every key.
-  // The write will succeed if the current DB version against the key is the same as in the request.
-  // When initiating a PutObjectRequest, the request should contain their client-side version for
+  // Clients are expected to store a `version` against every `key`.
+  // The write will succeed if the current DB version against the `key` is the same as in the request.
+  // When initiating a `PutObjectRequest`, the request should contain their client-side version for
   // that key-value.
   //
-  // For the first write of any key, the version should be '0'. If the write succeeds, the client
+  // For the first write of any key, the `version` should be '0'. If the write succeeds, the client
   // must increment their corresponding key versions (client-side) by 1.
   // The server increments key versions (server-side) for every successful write, hence this
   // client-side increment is required to ensure matching versions. These updated key versions should
@@ -89,7 +89,7 @@ message PutObjectRequest {
   // Considerations for transactions:
   // Transaction writes of multiple items have a performance overhead, hence it is recommended to use
   // them only if required by the client application to ensure logic/code correctness.
-  // That is, transaction_items are not a substitute for batch-write of multiple unrelated items.
+  // That is, `transaction_items` are not a substitute for batch-write of multiple unrelated items.
   // When a write of multiple unrelated items is desired, it is recommended to use separate
   // PutObjectRequests.
   //
@@ -98,11 +98,11 @@ message PutObjectRequest {
   // read-after-update consistency guarantees.
   repeated KeyValue transaction_items = 3;
 
-  // Items to be deleted as a result of this PutObjectRequest.
+  // Items to be deleted as a result of this `PutObjectRequest`.
   //
-  // Each item in the `delete_items` field consists of a key and its corresponding version.
-  // The version is used to perform a version check before deleting the item.
-  // The delete will only succeed if the current database version against the key is the same as the version
+  // Each item in the `delete_items` field consists of a `key` and its corresponding `version`.
+  // The `version` is used to perform a version check before deleting the item.
+  // The delete will only succeed if the current database version against the `key` is the same as the `version`
   // specified in the request.
   //
   // Fails with `CONFLICT_EXCEPTION` as the ErrorCode if:
@@ -122,23 +122,23 @@ message PutObjectResponse {
 
 // Request payload to be used for `DeleteObject` API call to server.
 message DeleteObjectRequest {
-  // store_id is a keyspace identifier.
+  // `store_id` is a keyspace identifier.
   // Ref: https://en.wikipedia.org/wiki/Keyspace_(distributed_data_store)
-  // All APIs operate within a single store_id.
+  // All APIs operate within a single `store_id`.
   // It is up to clients to use single or multiple stores for their use-case.
   // This can be used for client-isolation/ rate-limiting / throttling on the server-side.
-  // Authorization and billing can also be performed at the store_id level.
+  // Authorization and billing can also be performed at the `store_id` level.
   string store_id = 1;
 
-  // Item to be deleted as a result of this DeleteObjectRequest.
+  // Item to be deleted as a result of this `DeleteObjectRequest`.
   //
-  // An item consists of a key and its corresponding version.
-  // The item is only deleted if the current database version against the key is the same as the version
+  // An item consists of a `key` and its corresponding `version`.
+  // The item is only deleted if the current database version against the `key` is the same as the `version`
   // specified in the request.
   // This operation is idempotent, that is, multiple delete calls for the same item will not fail.
   //
   // If the requested item does not exist, this operation will not fail.
-  // If you wish to perform stricter checks while deleting an item, consider using PutObject API.
+  // If you wish to perform stricter checks while deleting an item, consider using `PutObject` API.
   KeyValue key_value = 2;
 }
 
@@ -149,79 +149,79 @@ message DeleteObjectResponse{
 // Request payload to be used for `ListKeyVersions` API call to server.
 message ListKeyVersionsRequest {
 
-  // store_id is a keyspace identifier.
+  // `store_id` is a keyspace identifier.
   // Ref: https://en.wikipedia.org/wiki/Keyspace_(distributed_data_store)
-  // All APIs operate within a single store_id.
+  // All APIs operate within a single `store_id`.
   // It is up to clients to use single or multiple stores for their use-case.
   // This can be used for client-isolation/ rate-limiting / throttling on the server-side.
-  // Authorization and billing can also be performed at the store_id level.
+  // Authorization and billing can also be performed at the `store_id` level.
   string store_id = 1;
 
-  // A key_prefix is a string of characters at the beginning of the key. Prefixes can be used as
+  // A `key_prefix` is a string of characters at the beginning of the key. Prefixes can be used as
   // a way to organize key-values in a similar way to directories.
   //
-  // If key_prefix is specified, the response results will be limited to those keys that begin with
+  // If `key_prefix` is specified, the response results will be limited to those keys that begin with
   // the specified prefix.
   //
-  // If no key_prefix is specified or it is empty (""), all the keys are eligible to be returned in
+  // If no `key_prefix` is specified or it is empty (""), all the keys are eligible to be returned in
   // the response.
   optional string key_prefix = 2;
 
-  // page_size is used by clients to specify the maximum number of results that can be returned by
+  // `page_size` is used by clients to specify the maximum number of results that can be returned by
   // the server.
   // The server may further constrain the maximum number of results returned in a single page.
-  // If the page_size is 0 or not set, the server will decide the number of results to be returned.
+  // If the `page_size` is 0 or not set, the server will decide the number of results to be returned.
   optional int32 page_size = 3;
 
-  // page_token is a pagination token.
+  // `page_token` is a pagination token.
   //
-  // To query for the first page of ListKeyVersions, page_token must not be specified.
+  // To query for the first page of `ListKeyVersions`, `page_token` must not be specified.
   //
   // For subsequent pages, use the value that was returned as `next_page_token` in the previous
-  // page's ListKeyVersionsResponse.
+  // page's `ListKeyVersionsResponse`.
   optional string page_token = 4;
 }
 
 // Server response for `ListKeyVersions` API.
 message ListKeyVersionsResponse {
 
   // Fetched keys and versions.
-  // Even though this API reuses KeyValue struct, the value sub-field will not be set by the server.
+  // Even though this API reuses the `KeyValue` struct, the `value` sub-field will not be set by the server.
   repeated KeyValue key_versions = 1;
 
-  // next_page_token is a pagination token, used to retrieve the next page of results.
-  // Use this value to query for next_page of paginated ListKeyVersions operation, by specifying
+  // `next_page_token` is a pagination token, used to retrieve the next page of results.
+  // Use this value to query for next-page of paginated `ListKeyVersions` operation, by specifying
   // this value as the `page_token` in the next request.
   //
-  // If next_page_token is empty (""), then the "last page" of results has been processed and
+  // If `next_page_token` is empty (""), then the "last page" of results has been processed and
   // there is no more data to be retrieved.
   //
-  // If next_page_token is not empty, it does not necessarily mean that there is more data in the
+  // If `next_page_token` is not empty, it does not necessarily mean that there is more data in the
   // result set. The only way to know when you have reached the end of the result set is when
-  // next_page_token is empty.
+  // `next_page_token` is empty.
   //
   // Caution: Clients must not assume a specific number of key_versions to be present in a page for
   // paginated response.
   optional string next_page_token = 2;
 
-  // global_version is a sequence-number/version of the whole store.
+  // `global_version` is a sequence-number/version of the whole store.
   //
-  // global_version is only returned in response for the first page of the ListKeyVersionsResponse
+  // `global_version` is only returned in response for the first page of the `ListKeyVersionsResponse`
   // and is guaranteed to be read before reading any key-versions.
   //
   // In case of refreshing the complete key-version view on the client-side, correct usage for
-  // the returned global_version is as following:
-  //   1. Read global_version from the first page of paginated response and save it as local variable.
-  //   2. Update all the key_versions on client-side from all the pages of paginated response.
-  //   3. Update global_version on client_side from the local variable saved in step-1.
-  // This ensures that on client-side, all current key_versions were stored at global_version or later.
-  // This guarantee is helpful for ensuring the versioning correctness if using the global_version
-  // in PutObject API and can help avoid the race conditions related to it.
+  // the returned `global_version` is as following:
+  //   1. Read `global_version` from the first page of paginated response and save it as local variable.
+  //   2. Update all the `key_versions` on client-side from all the pages of paginated response.
+  //   3. Update `global_version` on client_side from the local variable saved in step-1.
+  // This ensures that on client-side, all current `key_versions` were stored at `global_version` or later.
+  // This guarantee is helpful for ensuring the versioning correctness if using the `global_version`
+  // in `PutObject` API and can help avoid the race conditions related to it.
   optional int64 global_version = 3;
 }
 
-// When HttpStatusCode is not ok (200), the response `content` contains a serialized ErrorResponse
-// with the relevant ErrorCode and message
+// When HttpStatusCode is not ok (200), the response `content` contains a serialized `ErrorResponse`
+// with the relevant `ErrorCode` and `message`
 message ErrorResponse {
 
   // The error code uniquely identifying an error condition.
@@ -235,14 +235,14 @@ message ErrorResponse {
   string message = 2;
 }
 
-// ErrorCodes to be used in ErrorResponse
+// ErrorCodes to be used in `ErrorResponse`
 enum ErrorCode {
 
-  // Default protobuf Enum value. Will not be used as ErrorCode by server.
+  // Default protobuf Enum value. Will not be used as `ErrorCode` by server.
   UNKNOWN = 0;
 
   // CONFLICT_EXCEPTION is used when the request contains mismatched version (either key or global)
-  // in PutObjectRequest. For more info refer PutObjectRequest.
+  // in `PutObjectRequest`. For more info refer `PutObjectRequest`.
   CONFLICT_EXCEPTION= 1;
 
   // INVALID_REQUEST_EXCEPTION is used in the following cases:
@@ -256,18 +256,18 @@ enum ErrorCode {
   INTERNAL_SERVER_EXCEPTION = 3;
 }
 
-// Represents KeyValue pair to be stored or retrieved.
+// Represents a key-value pair to be stored or retrieved.
 message KeyValue {
 
   // Key against which the value is stored.
   string key = 1;
 
   // Version field is used for key-level versioning.
-  // For first write of key, version should be '0'. If the write succeeds, clients must increment
+  // For first write of key, `version` should be '0'. If the write succeeds, clients must increment
   // their corresponding key version (client-side) by 1.
   // The server increments key version (server-side) for every successful write, hence this
   // client-side increment is required to ensure matching versions. These updated key versions should
-  // be used in subsequent PutObjectRequests for the keys.
+  // be used in subsequent `PutObjectRequest`s for the keys.
   int64 version = 2;
 
   // Object value in bytes which is stored (in put) and fetched (in get).