tustvold commented on code in PR #5519: URL: https://github.com/apache/arrow-rs/pull/5519#discussion_r1526652628
########## object_store/src/lib.rs: ########## @@ -88,19 +88,24 @@ //! //! # Why not a Filesystem Interface? //! -//! Whilst this crate does provide a [`BufReader`], the [`ObjectStore`] interface mirrors the APIs -//! of object stores and not filesystems, opting to provide stateless APIs instead of the cursor -//! based interfaces such as [`Read`] or [`Seek`] favoured by filesystems. +//! The [`ObjectStore`] interface is designed to mirror the APIs +//! of object stores and *not* filesystems, and thus has stateless APIs instead +//! of cursor based interfaces such as [`Read`] or [`Seek`] available in filesystems. //! -//! This provides some compelling advantages: +//! This design provides the following advantages: //! //! * All operations are atomic, and readers cannot observe partial and/or failed writes //! * Methods map directly to object store APIs, providing both efficiency and predictability //! * Abstracts away filesystem and operating system specific quirks, ensuring portability //! * Allows for functionality not native to filesystems, such as operation preconditions //! and atomic multipart uploads //! +//! This crate does provide a [`BufReader`] and [`BufWriter`] adapters +//! which provide a more filesystem-like API for working with the +//! [`ObjectStore`] trait. Review Comment: ```suggestion //! [`ObjectStore`] trait, however, they should be used with care ``` ########## object_store/src/lib.rs: ########## @@ -88,19 +88,24 @@ //! //! # Why not a Filesystem Interface? //! -//! Whilst this crate does provide a [`BufReader`], the [`ObjectStore`] interface mirrors the APIs -//! of object stores and not filesystems, opting to provide stateless APIs instead of the cursor -//! based interfaces such as [`Read`] or [`Seek`] favoured by filesystems. +//! The [`ObjectStore`] interface is designed to mirror the APIs +//! of object stores and *not* filesystems, and thus has stateless APIs instead +//! of cursor based interfaces such as [`Read`] or [`Seek`] available in filesystems. //! -//! This provides some compelling advantages: +//! This design provides the following advantages: //! //! * All operations are atomic, and readers cannot observe partial and/or failed writes //! * Methods map directly to object store APIs, providing both efficiency and predictability //! * Abstracts away filesystem and operating system specific quirks, ensuring portability //! * Allows for functionality not native to filesystems, such as operation preconditions //! and atomic multipart uploads //! +//! This crate does provide a [`BufReader`] and [`BufWriter`] adapters Review Comment: ```suggestion //! This crate does provide [`BufReader`] and [`BufWriter`] adapters ``` -- 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]
