From 2dd8e776e7a8603944c8d24811f4232ebbf440bf Mon Sep 17 00:00:00 2001 From: Xuanwo Date: Thu, 29 Feb 2024 12:05:53 +0800 Subject: [PATCH] docs: Polish the docs for writer Signed-off-by: Xuanwo --- core/src/types/operator/operator.rs | 37 ++++++++++++++++++++++++----- 1 file changed, 31 insertions(+), 6 deletions(-) diff --git a/core/src/types/operator/operator.rs b/core/src/types/operator/operator.rs index dbf18c89d819..d12096606bca 100644 --- a/core/src/types/operator/operator.rs +++ b/core/src/types/operator/operator.rs @@ -718,7 +718,13 @@ impl Operator { /// ## Streaming Write /// /// This function will write all bytes at once. For more precise memory control or - /// writing data lazily, please use [`Operator::writer`]. + /// writing data continuously, please use [`Operator::writer`]. + /// + /// ## Multipart Uploads Write + /// + /// OpenDAL abstracts the multipart uploads into [`Writer`]. It will automatically + /// handle the multipart uploads for you. You can control the behavior of multipart uploads + /// by setting `buffer`, `concurrent` via [`Operator::writer_with`] /// /// # Examples /// @@ -867,6 +873,17 @@ impl Operator { /// extra options like `content_type` and `cache_control`, please use [`Operator::write_with`] /// instead. /// + /// ## Buffer + /// + /// OpenDAL is designed to write files directly without buffering by default, giving users + /// control over the exact size of their writes and helping avoid unnecessary costs. + /// + /// This is not efficient for cases when users write small chunks of data. Some storage services + /// like `s3` could even return hard errors like `EntityTooSmall`. Besides, cloud storage services + /// will cost more money if we write data in small chunks. + /// + /// Users can use [`Operator::write_with`] to set a good buffer size might improve the performance, + /// /// # Examples /// /// ``` @@ -923,12 +940,14 @@ impl Operator { /// /// Set `buffer` for the writer. /// - /// OpenDAL by default to write file without buffer. This is not efficient for cases when users - /// write small chunks of data. Some storage services like `s3` could even return hard errors - /// like `EntityTooSmall`. To improve performance, we can set a buffer. + /// OpenDAL is designed to write files directly without buffering by default, giving users + /// control over the exact size of their writes and helping avoid unnecessary costs. + /// + /// This is not efficient for cases when users write small chunks of data. Some storage services + /// like `s3` could even return hard errors like `EntityTooSmall`. Besides, cloud storage services + /// will cost more money if we write data in small chunks. /// - /// Besides, cloud storage services will cost more money if we write data in small chunks. Set - /// a good buffer size might reduce the API calls and save money. + /// Set a good buffer size might improve the performance, reduce the API calls and save money. /// /// The following example will set the writer buffer to 8MiB. Only one API call will be sent at /// `close` instead. @@ -1114,6 +1133,12 @@ impl Operator { /// This function will write all bytes at once. For more precise memory control or /// writing data lazily, please use [`Operator::writer_with`]. /// + /// ## Multipart Uploads Write + /// + /// OpenDAL abstracts the multipart uploads into [`Writer`]. It will automatically + /// handle the multipart uploads for you. You can control the behavior of multipart uploads + /// by setting `buffer`, `concurrent` via [`Operator::writer_with`] + /// /// # Options /// /// ## `append`