[BEAM-3221] Improve documentation in model pipeline protos

lukecwik · lukecwik · commit 309d11272810 · 2022-01-10T14:57:32.000-08:00
* clarify state caching tokens
* fix documentation around side input types and valid request types.
diff --git a/model/fn-execution/src/main/proto/beam_fn_api.proto b/model/fn-execution/src/main/proto/beam_fn_api.proto
@@ -268,8 +268,11 @@ message ProcessBundleRequest {
   // instantiated and executed by the SDK harness.
   string process_bundle_descriptor_id = 1;
 
-  // A cache token which can be used by an SDK to check for the validity
-  // of cached elements which have a cache token associated.
+  // Contains the cache token and also defines the scope of what the token applies to.
+  //
+  // See https://s.apache.org/beam-fn-state-api-and-bundle-processing#heading=h.7ghoih5aig5m
+  // for additional details on how to use the cache token with the State API
+  // to cache data across bundle boundaries.
   message CacheToken {
 
     // A flag to indicate a cache token is valid for all user state.
@@ -289,12 +292,17 @@ message ProcessBundleRequest {
       SideInput side_input = 2;
     }
 
-    // The cache token identifier which should be globally unique.
+    // An opaque token used with the StateKey to create a globally unique
+    // identifier.
     bytes token = 10;
   }
 
   // (Optional) A list of cache tokens that can be used by an SDK to reuse
   // cached data returned by the State API across multiple bundles.
+  //
+  // See https://s.apache.org/beam-fn-state-api-and-bundle-processing#heading=h.7ghoih5aig5m
+  // for additional details on how to use the cache token with the State API
+  // to cache data across bundle boundaries.
   repeated CacheToken cache_tokens = 2;
 
   // (Optional) Elements to be processed with the bundle. Either all or
diff --git a/model/pipeline/src/main/proto/beam_runner_api.proto b/model/pipeline/src/main/proto/beam_runner_api.proto
@@ -452,7 +452,7 @@ message StandardSideInputTypes {
     // Represents a view over a PCollection<KV<K, V>>.
     //
     // StateGetRequests performed on this side input must use
-    // StateKey.IterableSideInput or StateKey.MultimapSideInput.
+    // StateKey.MultimapKeysSideInput or StateKey.MultimapSideInput.
     MULTIMAP = 1 [(beam_urn) = "beam:side_input:multimap:v1"];
   }
 }
@@ -1354,9 +1354,8 @@ message SideInput {
   // This access pattern defines the SDK harness <-> Runner Harness RPC
   // interface for accessing a side input.
   //
-  // The only access pattern intended for Beam, because of its superior
-  // performance possibilities, is "beam:sideinput:multimap" (or some such
-  // URN)
+  // See StandardSideInputTypes for an enumeration of all side input types
+  // defined.
   FunctionSpec access_pattern = 1;
 
   // (Required) The FunctionSpec of the UDF that adapts a particular
