Minor: clarify the relationship between file::metadata and format (#6049)

Author: alamb

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.

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.
 //!

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