Add more comments

rust/types/src/metadata.rs

@@ -317,6 +317,13 @@ Metadata queries
 ===========================================
 */
 
+/// This `Where` enum serves as an unified representation for the `where` and `where_document` clauses.
+/// Although this is not unified in the API level due to legacy design choices, in the future we will be
+/// unifying them together, and the structure of the unified AST should be identical to the one here.
+/// Currently both `where` and `where_document` clauses will be translated into `Where`, and if both are
+/// present we simply create a conjunction of both clauses as the actual filter. This is consistent with
+/// the semantics we used to have when the `where` and `where_document` clauses are treated seperately.
+/// TODO: Remove this note once the `where` clause and `where_document` clause is unified in the API level.
 #[derive(Clone, Debug, PartialEq)]
 pub enum Where {
  DirectWhereComparison(DirectWhereComparison),

rust/worker/src/execution/operators/hydrate_metadata_results.rs

@@ -137,7 +137,8 @@ impl Operator<HydrateMetadataResultsOperatorInput, HydrateMetadataResultsOperato
  HydrateMetadataResultsOperatorError::LogMaterialization(e)
  })?;
 
- // A hash map that map an offset id to the corresponding log
+ // Create a hash map that maps an offset id to the corresponding log
+ // It contains all records from the logs that should be present in the final result
  let oid_to_log_record: HashMap<_, _> = mat_records
  .iter()
  .flat_map(|(log, _)| {

rust/worker/src/execution/operators/metadata_filtering.rs

@@ -530,7 +530,7 @@ impl Operator<MetadataFilteringInput, MetadataFilteringOutput> for MetadataFilte
  Include(rbm) => rbm,
  Exclude(rbm) => {
  if let Some(reader) = record_segment_reader.as_ref() {
- // TODO: Optimize offset limit performance
+ // TODO: Optimize for offset limit performance
  reader
  .get_all_offset_ids()
  .await