docs: fix references in public docs

crates/catalog/rest/src/catalog.rs

@@ -564,7 +564,7 @@ impl RestCatalog {
 }
 
 /// All requests and expected responses are derived from the REST catalog API spec:
-/// https://github.com/apache/iceberg/blob/main/open-api/rest-catalog-open-api.yaml
+/// <https://github.com/apache/iceberg/blob/main/open-api/rest-catalog-open-api.yaml>
 #[async_trait]
 impl Catalog for RestCatalog {
     async fn list_namespaces(

crates/iceberg/src/arrow/schema.rs

@@ -102,7 +102,7 @@ impl ExtensionType for VariantExtensionType {
 
 /// A post order arrow schema visitor.
 ///
-/// For order of methods called, please refer to [`visit_schema`].
+/// For order of methods called, please refer to the internal `visit_schema` function.
 pub trait ArrowSchemaVisitor {
     /// Return type of this visitor on arrow field.
     type T;

crates/iceberg/src/encryption/crypto.rs

@@ -34,7 +34,7 @@ use crate::{Error, ErrorKind, Result};
 
 /// Wrapper for sensitive byte data (encryption keys, DEKs, etc.) that:
 /// - Zeroizes memory on drop
-/// - Redacts content in [`Debug`] and [`Display`] output
+/// - Redacts content in [`Debug`](std::fmt::Debug) and [`Display`](std::fmt::Display) output
 /// - Provides only `&[u8]` access via [`as_bytes()`](Self::as_bytes)
 /// - Uses `Box<[u8]>` (immutable boxed slice) since key bytes never grow
 ///
@@ -217,7 +217,7 @@ impl AesGcmCipher {
     /// * `aad` - Additional authenticated data (optional)
     ///
     /// # Returns
-    /// The encrypted data in the format: [12-byte nonce][ciphertext][16-byte auth tag]
+    /// The encrypted data in the format: `[12-byte nonce][ciphertext][16-byte auth tag]`
     /// This matches the Java implementation format for compatibility.
     pub fn encrypt(&self, plaintext: &[u8], aad: Option<&[u8]>) -> Result<Vec<u8>> {
         match self.key_size {

crates/iceberg/src/encryption/manager.rs

@@ -161,7 +161,7 @@ impl EncryptionManager {
     ///
     /// Stores the resulting wrapped entry (and any newly created KEK) in the
     /// manager's internal `encryption_keys` map. Callers persist the full set
-    /// at commit time via [`Self::encryption_keys`].
+    /// at commit time via the manager's `encryption_keys`.
     ///
     /// Returns the `key_id` of the wrapped entry, which should be recorded on
     /// the snapshot as `encryption_key_id` so readers can locate it later.

crates/iceberg/src/io/storage/config/azdls.rs

@@ -51,7 +51,6 @@ pub const ADLS_AUTHORITY_HOST: &str = "adls.authority-host";
 ///
 /// This struct contains all the configuration options for connecting to Azure Data Lake Storage.
 /// Use the builder pattern via `AzdlsConfig::builder()` to construct instances.
-/// ```
 #[derive(Clone, Debug, Default, PartialEq, Eq, Serialize, Deserialize, TypedBuilder)]
 pub struct AzdlsConfig {
     /// Connection string.

crates/iceberg/src/io/storage/config/gcs.rs

@@ -18,7 +18,7 @@
 //! Google Cloud Storage configuration.
 //!
 //! This module provides configuration constants and types for Google Cloud Storage.
-//! Reference: https://github.com/apache/iceberg/blob/main/gcp/src/main/java/org/apache/iceberg/gcp/GCPProperties.java
+//! Reference: <https://github.com/apache/iceberg/blob/main/gcp/src/main/java/org/apache/iceberg/gcp/GCPProperties.java>
 
 use serde::{Deserialize, Serialize};
 use typed_builder::TypedBuilder;
@@ -52,7 +52,6 @@ pub const GCS_DISABLE_CONFIG_LOAD: &str = "gcs.disable-config-load";
 ///
 /// This struct contains all the configuration options for connecting to Google Cloud Storage.
 /// Use the builder pattern via `GcsConfig::builder()` to construct instances.
-/// ```
 #[derive(Clone, Debug, Default, PartialEq, Eq, Serialize, Deserialize, TypedBuilder)]
 pub struct GcsConfig {
     /// Google Cloud Project ID.

crates/iceberg/src/io/storage/config/mod.rs

@@ -50,7 +50,6 @@ use serde::{Deserialize, Serialize};
 /// This struct contains only configuration properties without specifying
 /// which storage backend to use. The storage type is determined by the
 /// explicit factory selection.
-/// ```
 #[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, Default)]
 pub struct StorageConfig {
     /// Configuration properties for the storage backend

crates/iceberg/src/io/storage/config/oss.rs

@@ -36,7 +36,6 @@ pub const OSS_ACCESS_KEY_SECRET: &str = "oss.access-key-secret";
 ///
 /// This struct contains all the configuration options for connecting to Alibaba Cloud OSS.
 /// Use the builder pattern via `OssConfig::builder()` to construct instances.
-/// ```
 #[derive(Clone, Debug, Default, PartialEq, Eq, Serialize, Deserialize, TypedBuilder)]
 pub struct OssConfig {
     /// OSS endpoint URL.

crates/iceberg/src/io/storage/local_fs.rs

@@ -50,7 +50,6 @@ use crate::{Error, ErrorKind, Result};
 /// - `file:///path/to/file` -> `/path/to/file`
 /// - `file:/path/to/file` -> `/path/to/file`
 /// - `/path/to/file` -> `/path/to/file`
-/// ```
 #[derive(Debug, Clone, Default, Serialize, Deserialize)]
 pub struct LocalFsStorage;
 

crates/iceberg/src/io/storage/memory.rs

@@ -58,7 +58,6 @@ use crate::{Error, ErrorKind, Result};
 /// deserialized, it creates a new empty instance. This is intentional
 /// because in-memory data cannot be meaningfully serialized across
 /// process boundaries.
-/// ```
 #[derive(Debug, Clone, Default, Serialize, Deserialize)]
 pub struct MemoryStorage {
     #[serde(skip, default = "default_memory_data")]

crates/iceberg/src/puffin/blob.rs

@@ -37,7 +37,7 @@ pub struct Blob {
 
 impl Blob {
     #[inline]
-    /// See blob types: https://iceberg.apache.org/puffin-spec/#blob-types
+    /// See blob types: <https://iceberg.apache.org/puffin-spec/#blob-types>
     pub fn blob_type(&self) -> &str {
         &self.r#type
     }

crates/iceberg/src/puffin/metadata.rs

@@ -29,7 +29,7 @@ use crate::{Error, ErrorKind, Result};
 pub const CREATED_BY_PROPERTY: &str = "created-by";
 
 /// Metadata about a blob.
-/// For more information, see: https://iceberg.apache.org/puffin-spec/#blobmetadata
+/// For more information, see: <https://iceberg.apache.org/puffin-spec/#blobmetadata>
 #[derive(Debug, PartialEq, Eq, Serialize, Deserialize, Clone)]
 #[serde(rename_all = "kebab-case")]
 pub struct BlobMetadata {
@@ -49,7 +49,7 @@ pub struct BlobMetadata {
 
 impl BlobMetadata {
     #[inline]
-    /// See blob types: https://iceberg.apache.org/puffin-spec/#blob-types
+    /// See blob types: <https://iceberg.apache.org/puffin-spec/#blob-types>
     pub fn blob_type(&self) -> &str {
         &self.r#type
     }
@@ -129,7 +129,7 @@ impl Flag {
 
 /// Metadata about a puffin file.
 ///
-/// For more information, see: https://iceberg.apache.org/puffin-spec/#filemetadata
+/// For more information, see: <https://iceberg.apache.org/puffin-spec/#filemetadata>
 #[derive(Debug, PartialEq, Eq, Serialize, Deserialize, Clone)]
 pub struct FileMetadata {
     pub(crate) blobs: Vec<BlobMetadata>,

crates/iceberg/src/runtime/mod.rs

@@ -26,7 +26,7 @@ use tokio::task;
 
 use crate::{Error, ErrorKind, Result};
 
-/// Wrapper around tokio's `JoinHandle` that converts task failures into
+/// Wrapper around tokio's [`tokio::task::JoinHandle`] that converts task failures into
 /// [`iceberg::Error`].
 ///
 /// Tokio's `JoinHandle<T>` resolves to `Result<T, JoinError>`, where a
@@ -53,7 +53,7 @@ impl<T: Send + 'static> Future for JoinHandle<T> {
 /// Wraps a [`tokio::runtime::Handle`], which is cheap to clone. The caller is
 /// responsible for keeping the underlying runtime alive while this handle is
 /// in use; spawning on a shut-down runtime will surface as a `JoinError` via
-/// [`JoinHandle`].
+/// the returned `JoinHandle`.
 #[derive(Clone)]
 pub struct RuntimeHandle {
     handle: tokio::runtime::Handle,
@@ -101,7 +101,7 @@ impl RuntimeHandle {
 /// A `Runtime` stores only `tokio::runtime::Handle`s (weak references). The
 /// caller owns the tokio runtime's lifetime. If the underlying runtime is
 /// dropped while iceberg is still using it, subsequent spawns will surface as
-/// task cancellation errors via [`JoinHandle`].
+/// task cancellation errors via the returned `JoinHandle`.
 ///
 /// Cloning is cheap.
 #[derive(Clone)]

crates/iceberg/src/spec/datatypes.rs

@@ -167,7 +167,7 @@ impl Type {
         }
     }
 
-    /// Return max precision for decimal given [`num_bytes`] bytes.
+    /// Return max precision for decimal given `num_bytes` bytes.
     #[inline(always)]
     pub fn decimal_max_precision(num_bytes: u32) -> Result<u32> {
         ensure_data_valid!(
@@ -177,7 +177,7 @@ impl Type {
         Ok(MAX_PRECISION[num_bytes as usize - 1])
     }
 
-    /// Returns minimum bytes required for decimal with [`precision`].
+    /// Returns minimum bytes required for decimal with `precision`.
     #[inline(always)]
     pub fn decimal_required_bytes(precision: u32) -> Result<u32> {
         ensure_data_valid!(

crates/iceberg/src/spec/manifest/data_file.rs

@@ -155,7 +155,7 @@ pub struct DataFile {
     /// field id: 142
     ///
     /// The _row_id for the first row in the data file.
-    /// For more details, refer to https://github.com/apache/iceberg/blob/main/format/spec.md#first-row-id-inheritance
+    /// For more details, refer to <https://github.com/apache/iceberg/blob/main/format/spec.md#first-row-id-inheritance>
     #[builder(default)]
     pub(crate) first_row_id: Option<i64>,
     /// This field is not included in spec. It is just store in memory representation used

crates/iceberg/src/spec/schema/mod.rs

@@ -364,25 +364,25 @@ impl Schema {
             .and_then(|id| self.field_by_id(*id))
     }
 
-    /// Returns [`highest_field_id`].
+    /// Returns the `highest_field_id`.
     #[inline]
     pub fn highest_field_id(&self) -> i32 {
         self.highest_field_id
     }
 
-    /// Returns [`schema_id`].
+    /// Returns the `schema_id`.
     #[inline]
     pub fn schema_id(&self) -> SchemaId {
         self.schema_id
     }
 
-    /// Returns [`r#struct`].
+    /// Returns the `r#struct`.
     #[inline]
     pub fn as_struct(&self) -> &StructType {
         &self.r#struct
     }
 
-    /// Returns [`identifier_field_ids`].
+    /// Returns the `identifier_field_ids`.
     #[inline]
     pub fn identifier_field_ids(&self) -> impl ExactSizeIterator<Item = i32> + '_ {
         self.identifier_field_ids.iter().copied()

crates/iceberg/src/spec/table_metadata.rs

@@ -1605,7 +1605,7 @@ pub struct SnapshotLog {
 }
 
 impl SnapshotLog {
-    /// Returns the last updated timestamp as a DateTime<Utc> with millisecond precision
+    /// Returns the last updated timestamp as a `DateTime<Utc>` with millisecond precision
     pub fn timestamp(self) -> Result<DateTime<Utc>> {
         timestamp_ms_to_utc(self.timestamp_ms)
     }

crates/iceberg/src/spec/table_properties.rs

@@ -318,7 +318,7 @@ impl TableProperties {
     pub const PROPERTY_PARQUET_CDC_NORM_LEVEL_DEFAULT: i32 = 0;
 
     /// Property key for the master key id used to encrypt the table's manifest
-    /// list and data files as defined in https://iceberg.apache.org/docs/nightly/encryption/.
+    /// list and data files as defined in <https://iceberg.apache.org/docs/nightly/encryption/>.
     pub const PROPERTY_ENCRYPTION_KEY_ID: &str = "encryption.key-id";
 
     /// Property key for the encryption data encryption key (DEK) length in bytes.

crates/iceberg/src/spec/values/datum.rs

@@ -822,7 +822,7 @@ impl Datum {
         Self::timestamp_micros(dt.and_utc().timestamp_micros())
     }
 
-    /// Parse a timestamp in [`%Y-%m-%dT%H:%M:%S%.f`] format.
+    /// Parse a timestamp in `%Y-%m-%dT%H:%M:%S%.f` format.
     ///
     /// See [`NaiveDateTime::from_str`].
     ///
@@ -1240,7 +1240,7 @@ impl Datum {
     /// Returns a human-readable string representation of this literal.
     ///
     /// For string literals, this returns the raw string value without quotes.
-    /// For all other literals, it falls back to [`to_string()`].
+    /// For all other literals, it falls back to [`to_string()`](ToString::to_string).
     pub fn to_human_string(&self) -> String {
         match self.literal() {
             PrimitiveLiteral::String(s) => s.to_string(),

crates/iceberg/src/spec/view_metadata.rs

@@ -225,7 +225,7 @@ impl ViewVersionLog {
         self.timestamp_ms
     }
 
-    /// Returns the last updated timestamp as a DateTime<Utc> with millisecond precision.
+    /// Returns the last updated timestamp as a `DateTime<Utc>` with millisecond precision.
     pub fn timestamp(&self) -> Result<DateTime<Utc>> {
         timestamp_ms_to_utc(self.timestamp_ms)
     }

crates/iceberg/src/test_utils.rs

@@ -34,7 +34,7 @@ use crate::spec::TableMetadata;
 use crate::table::Table;
 
 /// Returns a process-wide [`Runtime`] suitable for tests that need to construct
-/// a [`Table`](crate::table::Table) outside a tokio context.
+/// a [`Table`] outside a tokio context.
 ///
 /// The returned [`Runtime`] wraps a single shared multi-thread tokio runtime
 /// that is lazily built on first call and lives until process exit. Cloning is

crates/iceberg/src/transaction/update_schema.rs

@@ -32,12 +32,11 @@ use crate::{Error, ErrorKind, Result, TableRequirement, TableUpdate};
 // Default ID for a new column. This will be re-assigned to a fresh ID at commit time.
 const DEFAULT_FIELD_ID: i32 = 0;
 
-/// Declarative specification for adding a column in [`UpdateSchemaAction`].
+/// Declarative specification for adding a column in an `UpdateSchemaAction`.
 ///
 /// Use helper constructors such as [`AddColumn::optional`] and [`AddColumn::required`],
-/// optionally combined with [`AddColumn::with_parent`] and [`AddColumn::with_doc`], then pass
-/// the value to
-/// [`UpdateSchemaAction::add_column`].
+/// optionally combined with the builder's `parent` and `doc` setters via
+/// [`AddColumn::builder`], then pass the value to `UpdateSchemaAction::add_column`.
 #[derive(TypedBuilder)]
 pub struct AddColumn {
     #[builder(default = None, setter(strip_option, into))]

crates/integrations/datafusion/src/table/metadata_table.rs

@@ -34,8 +34,8 @@ use iceberg::table::Table;
 use crate::physical_plan::metadata_scan::IcebergMetadataScan;
 use crate::to_datafusion_error;
 
-/// Represents a [`TableProvider`] for the Iceberg [`Catalog`],
-/// managing access to a [`MetadataTable`].
+/// Represents a [`TableProvider`] for the Iceberg [`iceberg::Catalog`],
+/// managing access to a [`iceberg::inspect::MetadataTable`].
 #[derive(Debug, Clone)]
 pub struct IcebergMetadataTableProvider {
     pub(crate) table: Table,

crates/storage/opendal/src/lib.rs

@@ -18,8 +18,8 @@
 //! OpenDAL-based storage implementation for Apache Iceberg.
 //!
 //! This crate provides [`OpenDalStorage`] and [`OpenDalStorageFactory`],
-//! which implement the [`Storage`](Storage) and
-//! [`StorageFactory`](StorageFactory) traits from the `iceberg` crate
+//! which implement the [`Storage`] and
+//! [`StorageFactory`] traits from the `iceberg` crate
 //! using [OpenDAL](https://opendal.apache.org/) as the backend.
 
 mod utils;