chore: add docs, part of #37 (apache#6453)

* chore: add docs, part of #37
- add pragma `#![warn(missing_docs)]` to the following
  - `arrow-flight`
  - `arrow-ipc`
  - `arrow-integration-test`
  - `arrow-integration-testing`
  - `object_store`

- also document the caveat with using level 10 GZIP compression in
  parquet. See apache#6282.

* chore: resolve PR comments from apache#6453

Author: ByteBaker

src/aws/builder.rs

@@ -44,7 +44,6 @@ static DEFAULT_METADATA_ENDPOINT: &str = "http://169.254.169.254";
 
 /// A specialized `Error` for object store-related errors
 #[derive(Debug, Snafu)]
-#[allow(missing_docs)]
 enum Error {
     #[snafu(display("Missing bucket name"))]
     MissingBucketName,

src/aws/client.rs

@@ -65,7 +65,6 @@ const USER_DEFINED_METADATA_HEADER_PREFIX: &str = "x-amz-meta-";
 
 /// A specialized `Error` for object store-related errors
 #[derive(Debug, Snafu)]
-#[allow(missing_docs)]
 pub(crate) enum Error {
     #[snafu(display("Error performing DeleteObjects request: {}", source))]
     DeleteObjectsRequest { source: crate::client::retry::Error },

src/aws/resolve.rs

@@ -21,7 +21,6 @@ use snafu::{ensure, OptionExt, ResultExt, Snafu};
 
 /// A specialized `Error` for object store-related errors
 #[derive(Debug, Snafu)]
-#[allow(missing_docs)]
 enum Error {
     #[snafu(display("Bucket '{}' not found", bucket))]
     BucketNotFound { bucket: String },

src/azure/builder.rs

@@ -46,7 +46,6 @@ const MSI_ENDPOINT_ENV_KEY: &str = "IDENTITY_ENDPOINT";
 
 /// A specialized `Error` for Azure builder-related errors
 #[derive(Debug, Snafu)]
-#[allow(missing_docs)]
 enum Error {
     #[snafu(display("Unable parse source url. Url: {}, Error: {}", url, source))]
     UnableToParseUrl {

src/azure/client.rs

@@ -60,7 +60,6 @@ static TAGS_HEADER: HeaderName = HeaderName::from_static("x-ms-tags");
 
 /// A specialized `Error` for object store-related errors
 #[derive(Debug, Snafu)]
-#[allow(missing_docs)]
 pub(crate) enum Error {
     #[snafu(display("Error performing get request {}: {}", path, source))]
     GetRequest {

src/client/get.rs

@@ -96,7 +96,6 @@ impl ContentRange {
 
 /// A specialized `Error` for get-related errors
 #[derive(Debug, Snafu)]
-#[allow(missing_docs)]
 enum GetResultError {
     #[snafu(context(false))]
     Header {

src/lib.rs

@@ -1224,78 +1224,116 @@ pub type Result<T, E = Error> = std::result::Result<T, E>;
 
 /// A specialized `Error` for object store-related errors
 #[derive(Debug, Snafu)]
-#[allow(missing_docs)]
 #[non_exhaustive]
 pub enum Error {
+    /// A fallback error type when no variant matches
     #[snafu(display("Generic {} error: {}", store, source))]
     Generic {
+        /// The store this error originated from
         store: &'static str,
+        /// The wrapped error
         source: Box<dyn std::error::Error + Send + Sync + 'static>,
     },
 
+    /// Error when the object is not found at given location
     #[snafu(display("Object at location {} not found: {}", path, source))]
     NotFound {
+        /// The path to file
         path: String,
+        /// The wrapped error
         source: Box<dyn std::error::Error + Send + Sync + 'static>,
     },
 
+    /// Error for invalid path
     #[snafu(
         display("Encountered object with invalid path: {}", source),
         context(false)
     )]
-    InvalidPath { source: path::Error },
+    InvalidPath {
+        /// The wrapped error
+        source: path::Error,
+    },
 
+    /// Error when `tokio::spawn` failed
     #[snafu(display("Error joining spawned task: {}", source), context(false))]
-    JoinError { source: tokio::task::JoinError },
+    JoinError {
+        /// The wrapped error
+        source: tokio::task::JoinError,
+    },
 
+    /// Error when the attempted operation is not supported
     #[snafu(display("Operation not supported: {}", source))]
     NotSupported {
+        /// The wrapped error
         source: Box<dyn std::error::Error + Send + Sync + 'static>,
     },
 
+    /// Error when the object already exists
     #[snafu(display("Object at location {} already exists: {}", path, source))]
     AlreadyExists {
+        /// The path to the
         path: String,
+        /// The wrapped error
         source: Box<dyn std::error::Error + Send + Sync + 'static>,
     },
 
+    /// Error when the required conditions failed for the operation
     #[snafu(display("Request precondition failure for path {}: {}", path, source))]
     Precondition {
+        /// The path to the file
         path: String,
+        /// The wrapped error
         source: Box<dyn std::error::Error + Send + Sync + 'static>,
     },
 
+    /// Error when the object at the location isn't modified
     #[snafu(display("Object at location {} not modified: {}", path, source))]
     NotModified {
+        /// The path to the file
         path: String,
+        /// The wrapped error
         source: Box<dyn std::error::Error + Send + Sync + 'static>,
     },
 
+    /// Error when an operation is not implemented
     #[snafu(display("Operation not yet implemented."))]
     NotImplemented,
 
+    /// Error when the used credentials don't have enough permission
+    /// to perform the requested operation
     #[snafu(display(
         "The operation lacked the necessary privileges to complete for path {}: {}",
         path,
         source
     ))]
     PermissionDenied {
+        /// The path to the file
         path: String,
+        /// The wrapped error
         source: Box<dyn std::error::Error + Send + Sync + 'static>,
     },
 
+    /// Error when the used credentials lack valid authentication
     #[snafu(display(
         "The operation lacked valid authentication credentials for path {}: {}",
         path,
         source
     ))]
     Unauthenticated {
+        /// The path to the file
         path: String,
+        /// The wrapped error
         source: Box<dyn std::error::Error + Send + Sync + 'static>,
     },
 
+    /// Error when a configuration key is invalid for the store used
     #[snafu(display("Configuration key: '{}' is not valid for store '{}'.", key, store))]
-    UnknownConfigurationKey { store: &'static str, key: String },
+    UnknownConfigurationKey {
+        /// The object store used
+        store: &'static str,
+        /// The configuration key used
+        key: String,
+    },
 }
 
 impl From<Error> for std::io::Error {

src/local.rs

@@ -44,7 +44,6 @@ use crate::{
 
 /// A specialized `Error` for filesystem object store-related errors
 #[derive(Debug, Snafu)]
-#[allow(missing_docs)]
 pub(crate) enum Error {
     #[snafu(display("File size for {} did not fit in a usize: {}", path, source))]
     FileSizeOverflowedUsize {

src/memory.rs

@@ -38,7 +38,6 @@ use crate::{GetOptions, PutPayload};
 
 /// A specialized `Error` for in-memory object store-related errors
 #[derive(Debug, Snafu)]
-#[allow(missing_docs)]
 enum Error {
     #[snafu(display("No data in memory found. Location: {path}"))]
     NoDataInMemory { path: String },

src/path/mod.rs

@@ -36,32 +36,57 @@ pub use parts::{InvalidPart, PathPart};
 
 /// Error returned by [`Path::parse`]
 #[derive(Debug, Snafu)]
-#[allow(missing_docs)]
 #[non_exhaustive]
 pub enum Error {
+    /// Error when there's an empty segment between two slashes `/` in the path
     #[snafu(display("Path \"{}\" contained empty path segment", path))]
-    EmptySegment { path: String },
+    EmptySegment {
+        /// The source path
+        path: String,
+    },
 
+    /// Error when an invalid segment is encountered in the given path
     #[snafu(display("Error parsing Path \"{}\": {}", path, source))]
-    BadSegment { path: String, source: InvalidPart },
+    BadSegment {
+        /// The source path
+        path: String,
+        /// The part containing the error
+        source: InvalidPart,
+    },
 
+    /// Error when path cannot be canonicalized
     #[snafu(display("Failed to canonicalize path \"{}\": {}", path.display(), source))]
     Canonicalize {
+        /// The source path
         path: std::path::PathBuf,
+        /// The underlying error
         source: std::io::Error,
     },
 
+    /// Error when the path is not a valid URL
     #[snafu(display("Unable to convert path \"{}\" to URL", path.display()))]
-    InvalidPath { path: std::path::PathBuf },
+    InvalidPath {
+        /// The source path
+        path: std::path::PathBuf,
+    },
 
+    /// Error when a path contains non-unicode characters
     #[snafu(display("Path \"{}\" contained non-unicode characters: {}", path, source))]
     NonUnicode {
+        /// The source path
         path: String,
+        /// The underlying `UTF8Error`
         source: std::str::Utf8Error,
     },
 
+    /// Error when the a path doesn't start with given prefix
     #[snafu(display("Path {} does not start with prefix {}", path, prefix))]
-    PrefixMismatch { path: String, prefix: String },
+    PrefixMismatch {
+        /// The source path
+        path: String,
+        /// The mismatched prefix
+        prefix: String,
+    },
 }
 
 /// A parsed path representation that can be safely written to object storage