Improve comments

Author: c-thiel

crates/iceberg/src/spec/table_metadata.rs

@@ -308,11 +308,22 @@ impl TableMetadata {
         &self.properties
     }
 
-    /// Normalize this partition spec. This is an internal method
+    /// Normalize this partition spec.
+    ///
+    /// This is an internal method
     /// meant to be called after constructing table metadata from untrusted sources.
     /// We run this method after json deserialization.
     /// All constructors for `TableMetadata` which are part of `iceberg-rust`
     /// should return normalized `TableMetadata`.
+    ///
+    /// It does:
+    /// * Validate the current schema is set and valid
+    /// * Validate that all refs are valid (snapshot exists)
+    /// * Validate logs are chronological
+    /// * Normalize location (remove trailing slash)
+    /// * Validate that for V1 Metadata the last_sequence_number is 0
+    /// * If the default partition spec is specified but the spec is not present in specs, add it
+    /// * If the default sort order is unsorted but the sort order is not present, add it
     pub(super) fn try_normalize(&mut self) -> Result<&mut Self> {
         self.validate_current_schema()?;
         self.normalize_current_snapshot()?;