Update comments and docs.

Author: shaunrd0

test/src/unit-cppapi-enumerations.cc

@@ -334,17 +334,12 @@ TEST_CASE_METHOD(
     CPPEnumerationFx,
     "CPP API: Load All Enumerations - All Schemas",
     "[enumeration][array][load-all-enumerations][all-schemas][rest]") {
-  auto cfg = ctx_.config();
-  cfg["rest.use_refactored_array_open"] = "false";
-  cfg["rest.use_refactored_array_open_and_query_submit"] = "false";
-  vfs_test_setup_.update_config(cfg.ptr().get());
-  ctx_ = vfs_test_setup_.ctx();
   create_array();
 
   // Loading the array with array open v1 will only initialize the latest schema
   // For the first test this is fine, we only need to load enumerations for the
   // latest schema. In subsequent tests we will need to call
-  // ArrayExperimental::load_all_enumerations.
+  // ArrayExperimental::load_enumerations_all_schemas.
   auto array = tiledb::Array(ctx_, uri_, TILEDB_READ);
   auto schema = array.load_schema(ctx_, uri_);
   REQUIRE(

tiledb/sm/array/array.cc

@@ -959,11 +959,11 @@ void Array::load_all_enumerations(bool all_schemas) {
   }
   // Load all enumerations, discarding the returned list of loaded enumerations.
   if (all_schemas) {
-    // TODO: The enumerations are all here in a single request, they just need
-    // to be stored in a schema. Since array open v1 does not initialize
-    // array_schemas_all, we need to either serialize the full schemas with
-    // LoadEnumerationsResponse, or reopen the array using array open v2 (only
-    // if the config is set to use v1).
+    // Since array open v1 does not initialize array_schemas_all, we need to
+    // either serialize the full schemas with LoadEnumerationsResponse, or
+    // reopen the array using array open v2 (only if the config is set to use
+    // v1) so that we can store the enumerations from the response in the
+    // correct schemas using the schema names.
 
     // For now, reopen the array if it's found to be using array open v1.
     // Once we update to use post_array_schema_from_rest we will always have

tiledb/sm/array/array.h

@@ -573,7 +573,7 @@ class Array {
    *
    * This function retrieves the enumeration for the given name. If the
    * corresponding enumeration has not been loaded from storage it is
-   * loaded before this function returns.
+   * loaded and stored in the latest schema before this function returns.
    *
    * @param enumeration_name The name of the enumeration.
    * @return shared_ptr<const Enumeration> or nullptr on failure.
@@ -583,6 +583,9 @@ class Array {
 
   /**
    * Load enumerations on all schemas for the array's opened timestamp range.
+   * This function will store all loaded enumerations into their corresponding
+   * schemas. The returned enumerations are provided as a convenience to the
+   * caller and can be discarded if loading the enumerations is sufficient.
    *
    * @return Map of schema names and a list of all loaded enumerations.
    */

tiledb/sm/serialization/enumeration.cc

@@ -201,8 +201,8 @@ load_enumerations_response_from_capnp(
       loaded_enmrs.push_back(
           enumeration_from_capnp(enmr_reader, memory_tracker));
     }
-    // The name of the array schema will not be used if we only loaded
-    // enumerations on the latest array schema.
+    // The name of the latest array schema will not be serialized in the
+    // response if we are only loading enumerations from the latest schema.
     return {{array.array_schema_latest().name(), loaded_enmrs}};
   } else if (reader.hasAllEnumerations()) {
     auto all_enmrs_reader = reader.getAllEnumerations();

tiledb/sm/serialization/tiledb-rest.capnp

@@ -1266,10 +1266,12 @@ struct LoadEnumerationsRequest {
 
 struct LoadEnumerationsResponse {
   enumerations @0 :List(Enumeration);
-  # The loaded enumerations
+  # The loaded enumerations for the latest array schema
+  # This field is only used if enumerations are requested for the latest schema
 
   allEnumerations @1 :MapEnumeration;
   # The loaded enumerations for all array schemas
+  # This field is only used if enumerations are requested for all schemas
 }
 
 struct LoadArraySchemaRequest {