i like writing doc

Author: CTTY

crates/iceberg/src/transaction/validate.rs

@@ -36,18 +36,46 @@ use crate::{Error, ErrorKind};
 static VALIDATE_ADDED_DELETE_FILES_OPERATIONS: Lazy<HashSet<Operation>> =
     Lazy::new(|| HashSet::from([Operation::Overwrite, Operation::Delete]));
 
+/// A trait for validating snapshots in an Iceberg table.
+///
+/// This trait provides methods to validate snapshots and their history,
+/// ensuring data integrity and consistency across table operations.
 pub(crate) trait SnapshotValidator {
-    // todo doc
-    // table: base table
-    // snapshot: parent snapshot
-    // usually snapshot is the latest snapshot of base table, unless it's non-main branch
-    // but we don't support writing to branches as of now
+    /// Validates a snapshot against a table.
+    ///
+    /// # Arguments
+    ///
+    /// * `base` - The base table to validate against
+    /// * `parent_snapshot_id` - The ID of the parent snapshot, if any. This is usually
+    ///   the latest snapshot of the base table, unless it's a non-main branch
+    ///   (note: writing to branches is not currently supported)
+    ///
+    /// # Returns
+    ///
+    /// A `Result` indicating success or an error if validation fails
     async fn validate(&self, _base: &Table, _parent_snapshot_id: Option<i64>) -> Result<()> {
-        // todo: add default implementation
         Ok(())
     }
 
-    // todo doc
+    /// Retrieves the history of snapshots between two points with matching operations and content type.
+    ///
+    /// # Arguments
+    ///
+    /// * `base` - The base table to retrieve history from
+    /// * `from_snapshot_id` - The starting snapshot ID (exclusive), or None to start from the beginning
+    /// * `to_snapshot_id` - The ending snapshot ID (inclusive)
+    /// * `matching_operations` - Set of operations to match when collecting snapshots
+    /// * `manifest_content_type` - The content type of manifests to collect
+    ///
+    /// # Returns
+    ///
+    /// A tuple containing:
+    /// * A vector of manifest files matching the criteria
+    /// * A set of snapshot IDs that were collected
+    ///
+    /// # Errors
+    ///
+    /// Returns an error if the history between the snapshots cannot be determined
     async fn validation_history(
         &self,
         base: &Table,
@@ -104,6 +132,23 @@ pub(crate) trait SnapshotValidator {
         Ok((manifests, new_snapshots))
     }
 
+    /// Validates that there are no new delete files for the given data files.
+    ///
+    /// # Arguments
+    ///
+    /// * `base` - The base table to validate against
+    /// * `from_snapshot_id` - The starting snapshot ID (exclusive), or None to start from the beginning
+    /// * `to_snapshot_id` - The ending snapshot ID (inclusive), or None if there is no current table state
+    /// * `data_files` - The data files to check for conflicting delete files
+    /// * `ignore_equality_deletes` - Whether to ignore equality deletes and only check for positional deletes
+    ///
+    /// # Returns
+    ///
+    /// A `Result` indicating success or an error if validation fails
+    ///
+    /// # Errors
+    ///
+    /// Returns an error if new delete files are found for any of the data files
     async fn validate_no_new_delete_files_for_data_files(
         &self,
         base: &Table,