kylebarron commented on code in PR #551:
URL:
https://github.com/apache/arrow-rs-object-store/pull/551#discussion_r2548196493
##########
src/lib.rs:
##########
@@ -615,66 +620,31 @@ pub type MultipartId = String;
/// Universal API to multiple object store services.
///
-/// For more convenience methods, check [`ObjectStoreExt`].
+/// See the [module-level documentation](crate) for a high leve overview and
+/// examples. See [`ObjectStoreExt`] for additional convenience methods.
///
/// # Contract
-/// This trait is meant as a contract between object store implementations
-/// (e.g. providers, wrappers) and the `object_store` crate itself and is
+/// This trait is a contract between object store implementations
+/// (e.g. providers, wrappers) and the `object_store` crate itself. It is
/// intended to be the minimum API required for an object store.
///
-/// The [`ObjectStoreExt`] acts as an API/contract between `object_store`
-/// and the store users and provides additional methods that may be simpler to
use but overlap
-/// in functionality with [`ObjectStore`].
-///
-/// # Wrappers
-/// If you wrap an [`ObjectStore`] -- e.g. to add observability -- you SHOULD
-/// implement all trait methods. This ensures that defaults implementations
-/// that are overwritten by the wrapped store are also used by the wrapper.
-/// For example:
-///
-/// ```ignore
-/// struct MyStore {
-/// ...
-/// }
-///
-/// #[async_trait]
-/// impl ObjectStore for MyStore {
-/// // implement custom ranges handling
-/// async fn get_ranges(
-/// &self,
-/// location: &Path,
-/// ranges: &[Range<u64>],
-/// ) -> Result<Vec<Bytes>> {
-/// ...
-/// }
-///
-/// ...
-/// }
+/// The [`ObjectStoreExt`] acts as an API/contract between `object_store` and
+/// the store users and provides additional methods that may be simpler to use
Review Comment:
```suggestion
/// the store _users_ and provides additional methods that may be simpler to
use
```
##########
src/lib.rs:
##########
@@ -615,66 +620,31 @@ pub type MultipartId = String;
/// Universal API to multiple object store services.
///
-/// For more convenience methods, check [`ObjectStoreExt`].
+/// See the [module-level documentation](crate) for a high leve overview and
+/// examples. See [`ObjectStoreExt`] for additional convenience methods.
///
/// # Contract
-/// This trait is meant as a contract between object store implementations
-/// (e.g. providers, wrappers) and the `object_store` crate itself and is
+/// This trait is a contract between object store implementations
Review Comment:
```suggestion
/// This trait is a contract between object store _implementations_
```
##########
src/lib.rs:
##########
@@ -615,66 +620,31 @@ pub type MultipartId = String;
/// Universal API to multiple object store services.
///
-/// For more convenience methods, check [`ObjectStoreExt`].
+/// See the [module-level documentation](crate) for a high leve overview and
Review Comment:
```suggestion
/// See the [module-level documentation](crate) for a high level overview and
```
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
