From b72098fee551086b2b4eb4b131aeaf920cf7e4b3 Mon Sep 17 00:00:00 2001
From: Andrew Lamb <andrew@nerdnetworks.org>
Date: Tue, 16 Jul 2024 18:31:53 -0400
Subject: [PATCH] Minor: clarify the relationship between `file::metadata` and
 `format` (#6049)

---
 parquet/src/file/metadata/mod.rs | 6 +++++-
 parquet/src/file/mod.rs          | 2 +-
 parquet/src/lib.rs               | 7 ++++++-
 3 files changed, 12 insertions(+), 3 deletions(-)

diff --git a/parquet/src/file/metadata/mod.rs b/parquet/src/file/metadata/mod.rs
index 40922d52bfd4..46ebf5d0f2b8 100644
--- a/parquet/src/file/metadata/mod.rs
+++ b/parquet/src/file/metadata/mod.rs
@@ -15,7 +15,11 @@
 // specific language governing permissions and limitations
 // under the License.
 
-//! Parquet metadata structures
+//! Parquet metadata API
+//!
+//! Most users should use these structures to interact with Parquet metadata.
+//! The [crate::format] module contains lower level structures generated from the
+//! Parquet thrift definition.
 //!
 //! * [`ParquetMetaData`]: Top level metadata container, read from the Parquet
 //!   file footer.
diff --git a/parquet/src/file/mod.rs b/parquet/src/file/mod.rs
index a1df33633fc7..12ff35b51646 100644
--- a/parquet/src/file/mod.rs
+++ b/parquet/src/file/mod.rs
@@ -15,7 +15,7 @@
 // specific language governing permissions and limitations
 // under the License.
 
-//! Low level APIs for reading raw parquet data.
+//! APIs for reading parquet data.
 //!
 //! Provides access to file and row group readers and writers, record API, metadata, etc.
 //!
diff --git a/parquet/src/lib.rs b/parquet/src/lib.rs
index f8342453fec7..543c629d3425 100644
--- a/parquet/src/lib.rs
+++ b/parquet/src/lib.rs
@@ -109,7 +109,12 @@ macro_rules! experimental {
 pub mod errors;
 pub mod basic;
 
-/// Automatically generated code for reading parquet thrift definition.
+/// Automatically generated code from the Parquet thrift definition.
+///
+/// This module code generated from [parquet.thrift]. See [crate::file] for
+/// more information on reading Parquet encoded data.
+///
+/// [parquet.thrift]: https://github.com/apache/parquet-format/blob/master/src/main/thrift/parquet.thrift
 // see parquet/CONTRIBUTING.md for instructions on regenerating
 #[allow(clippy::derivable_impls, clippy::match_single_binding)]
 // Don't try and format auto generated code