(opendal) branch main updated: docs: Polish the docs for writer (#4296)

[xu...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

xuanwo pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/opendal.git


The following commit(s) were added to refs/heads/main by this push:
     new 39afc09501 docs: Polish the docs for writer (#4296)
39afc09501 is described below

commit 39afc09501c4663567177de5fd0288025365ab0b
Author: Xuanwo <gi...@xuanwo.io>
AuthorDate: Thu Feb 29 20:38:41 2024 +0800

    docs: Polish the docs for writer (#4296)
---
 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 dbf18c89d8..d12096606b 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`