Minor: add additional documentation about BufWriter (#5519)

* Minor: add additional documentation about BufWriter

* Update object_store/src/buffered.rs

* Apply suggestions from code review

Co-authored-by: Raphael Taylor-Davies <1781103+tustvold@users.noreply.github.com>

* Format

---------

Co-authored-by: Raphael Taylor-Davies <1781103+tustvold@users.noreply.github.com>
Co-authored-by: Raphael Taylor-Davies <r.taylordavies@googlemail.com>

object_store/src/buffered.rs

@@ -207,6 +207,10 @@ impl AsyncBufRead for BufReader {
 
 /// An async buffered writer compatible with the tokio IO traits
 ///
+/// This writer adaptively uses [`ObjectStore::put`] or
+/// [`ObjectStore::put_multipart`] depending on the amount of data that has
+/// been written.
+///
 /// Up to `capacity` bytes will be buffered in memory, and flushed on shutdown
 /// using [`ObjectStore::put`]. If `capacity` is exceeded, data will instead be
 /// streamed using [`ObjectStore::put_multipart`]
@@ -255,7 +259,8 @@ impl BufWriter {
         }
     }
 
-    /// Returns the [`MultipartId`] if multipart upload
+    /// Returns the [`MultipartId`] of the multipart upload created by this
+    /// writer, if any.
     pub fn multipart_id(&self) -> Option<&MultipartId> {
         self.multipart_id.as_ref()
     }

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 [`BufReader`] and [`BufWriter`] adapters
+//! which provide a more filesystem-like API for working with the
+//! [`ObjectStore`] trait, however, they should be used with care
+//!
 //! [`BufReader`]: buffered::BufReader
+//! [`BufWriter`]: buffered::BufWriter
 //!
 //! # Adapters
 //!