From 17d3e20fd78804736c97e0ff0d5f0656aa35f16b Mon Sep 17 00:00:00 2001
From: Jack Dockerty <jdockerty19@gmail.com>
Date: Thu, 12 Jun 2025 12:45:49 +0100
Subject: [PATCH 1/2] docs: expand transaction mod with example

---
 crates/iceberg/src/transaction/mod.rs | 34 +++++++++++++++++++++++++++
 1 file changed, 34 insertions(+)

diff --git a/crates/iceberg/src/transaction/mod.rs b/crates/iceberg/src/transaction/mod.rs
index a592258a0d..d5868104fd 100644
--- a/crates/iceberg/src/transaction/mod.rs
+++ b/crates/iceberg/src/transaction/mod.rs
@@ -16,6 +16,40 @@
 // under the License.
 
 //! This module contains transaction api.
+//!
+//! The transaction API enables changes to be made to an existing table.
+//!
+//! Note that this may also have side effects, such as producing new manifest
+//! files.
+//!
+//! Below is a basic example using the "fast-append" action:
+//!
+//! ```ignore
+//! // Create a transaction.
+//! let tx = Transaction::new(my_table);
+//!
+//! // Create a `FastAppendAction` which will not rewrite or append
+//! // to existing metadata. This will create a new manifest.
+//! let mut action = tx
+//!     .fast_append(None, Vec::new())
+//!     .expect("a transaction can be validated with this input");
+//!
+//! action
+//!     .add_data_files(my_data_files)
+//!     .unwrap();
+//!
+//! let tx = action
+//!     .apply()
+//!     .await
+//!     .unwrap();
+//!
+//! // End the transaction by committing to an `iceberg::Catalog`
+//! // implementation. This will cause a table update to occur.
+//! let table = tx
+//!     .commit(some_catalog_impl)
+//!     .await
+//!     .unwrap();
+//! ```
 
 mod action;
 mod append;

From f9d66d386f57c1fc840bf38809286e2b444ebc3a Mon Sep 17 00:00:00 2001
From: Jack Dockerty <jdockerty19@gmail.com>
Date: Tue, 24 Jun 2025 09:49:46 +0100
Subject: [PATCH 2/2] docs: align to new transaction usage

---
 crates/iceberg/src/transaction/mod.rs | 19 ++++++++-----------
 1 file changed, 8 insertions(+), 11 deletions(-)

diff --git a/crates/iceberg/src/transaction/mod.rs b/crates/iceberg/src/transaction/mod.rs
index c9686b2cdc..913a02455f 100644
--- a/crates/iceberg/src/transaction/mod.rs
+++ b/crates/iceberg/src/transaction/mod.rs
@@ -25,28 +25,25 @@
 //! Below is a basic example using the "fast-append" action:
 //!
 //! ```ignore
+//! use iceberg::transaction::{ApplyTransactionAction, Transaction};
+//! use iceberg::Catalog;
+//!
 //! // Create a transaction.
 //! let tx = Transaction::new(my_table);
 //!
 //! // Create a `FastAppendAction` which will not rewrite or append
 //! // to existing metadata. This will create a new manifest.
-//! let mut action = tx
-//!     .fast_append(None, Vec::new())
-//!     .expect("a transaction can be validated with this input");
+//! let action = tx.fast_append().add_data_files(my_data_files);
 //!
-//! action
-//!     .add_data_files(my_data_files)
-//!     .unwrap();
+//! // Apply the fast-append action to the given transaction, returning
+//! // the newly updated `Transaction`.
+//! let tx = action.apply(tx).unwrap();
 //!
-//! let tx = action
-//!     .apply()
-//!     .await
-//!     .unwrap();
 //!
 //! // End the transaction by committing to an `iceberg::Catalog`
 //! // implementation. This will cause a table update to occur.
 //! let table = tx
-//!     .commit(some_catalog_impl)
+//!     .commit(&some_catalog_impl)
 //!     .await
 //!     .unwrap();
 //! ```