From a31c48a5859c1ac1b33005241060672cce905d49 Mon Sep 17 00:00:00 2001 From: meteorgan Date: Wed, 25 Sep 2024 23:08:18 +0800 Subject: [PATCH 1/2] docs(core): add the description of version parameter for operator --- core/src/types/operator/operator.rs | 118 ++++++++++++++++++++++++++++ 1 file changed, 118 insertions(+) diff --git a/core/src/types/operator/operator.rs b/core/src/types/operator/operator.rs index 0e8af02989eb..d81fed53e675 100644 --- a/core/src/types/operator/operator.rs +++ b/core/src/types/operator/operator.rs @@ -245,6 +245,25 @@ impl Operator { /// # } /// ``` /// + /// ## `version` + /// + /// Set `version` for this `stat` request. + /// + /// This feature can be used to retrieve the file metadata that matches a specified version. + /// + /// If file exists, but the version doesn't match, an error with kind [`ErrorKind::NotFound`] + /// will be returned. + /// + /// ```no_run + /// # use opendal::Result; + /// # use opendal::Operator; + /// + /// # async fn test(op: Operator, version: &str) -> Result<()> { + /// let mut metadata = op.stat_with("path/to/file").version(version).await?; + /// # Ok(()) + /// # } + /// ``` + /// /// # Examples /// /// ## Get metadata while `ETag` matches @@ -547,6 +566,26 @@ impl Operator { /// # } /// ``` /// + /// ## `version` + /// + /// Set `version` for this `read` request. + /// + /// By default, OpenDAL reads a file using the current version. By setting the `version`, OpenDAL will read + /// the file with the specified version. + /// + /// If the file exists, but the version doesn't match, an error with kind [`ErrorKind::NotFound`] + /// will be returned. + /// + /// ```no_run + /// # use opendal::Result; + /// # use opendal::Operator; + /// + /// # async fn test(op: Operator, version: &str) -> Result<()> { + /// let mut bs = op.read_with("path/to/file").version(version).await?; + /// # Ok(()) + /// # } + /// ``` + /// /// # Examples /// /// Read the whole path into a bytes. @@ -666,6 +705,26 @@ impl Operator { /// # } /// ``` /// + /// ## `version` + /// + /// Set `version` for this `reader`. + /// + /// By default, OpenDAL reads a file using the current version. By setting the `version`, OpenDAL will read + /// the file with the specified version. + /// + /// If the file exists, but the version doesn't match, an error with kind [`ErrorKind::NotFound`] + /// will be returned. + /// + /// ```no_run + /// # use opendal::Result; + /// # use opendal::Operator; + /// + /// # async fn test(op: Operator, version: &str) -> Result<()> { + /// let mut bs = op.reader_with("path/to/file").version(version).await?; + /// # Ok(()) + /// # } + /// ``` + /// /// # Examples /// /// ```no_run @@ -1481,6 +1540,30 @@ impl Operator { /// /// - Deleting a file that does not exist won't return errors. /// + /// # Options + /// + /// ## `version` + /// + /// Set `version` for this `delete` request. + /// + /// If `versioning` is not enabled, a `delete` request will permanently remove the file. + /// + /// when `versioning` is enabled, a simple `delete` request won't permanently remove the file, + /// it can still be accessed using its version. + /// By setting the `version`, OpenDAL will permanently remove the file with the specified version. + /// + /// If the file exists, but the version doesn't match, OpenDAL will not return errors. + /// + /// ```no_run + /// # use opendal::Result; + /// # use opendal::Operator; + /// + /// # async fn test(op: Operator, version: &str) -> Result<()> { + /// op.delete_with("path/to/file").version(version).await?; + /// # Ok(()) + /// # } + ///``` + /// /// # Examples /// /// ``` @@ -1785,6 +1868,23 @@ impl Operator { /// # Ok(()) /// # } /// ``` + /// ## `version` + /// + /// Specify whether to list all object versions or not + /// + /// if `version` is not set, or is set to false, only the active files with the current version will be returned. + /// + /// when `version` is set to true and the backend service has `versioning` enabled, all object versions will be returned. + /// if `versioning` is not enabled, an error with kind [`ErrorKind::Unsupported`] will be returned. + /// + /// ```no_run + /// # use opendal::Result; + /// # use opendal::Operator; + /// # async fn test(op: Operator) -> Result<()> { + /// let mut entries = op.list_with("path/to/dir/").version(true).await?; + /// # Ok(()) + /// # } + /// ``` /// /// # Examples /// @@ -1936,6 +2036,24 @@ impl Operator { /// # } /// ``` /// + /// ## `version` + /// + /// Specify whether to list all object versions or not + /// + /// if `version` is not set, or is set to false, only the active files with the current version will be returned. + /// + /// when `version` is set to true and the backend service has `versioning` enabled, all object versions will be returned. + /// if `versioning` is not enabled, an error with kind [`ErrorKind::Unsupported`] will be returned. + /// + /// ```no_run + /// # use opendal::Result; + /// # use opendal::Operator; + /// # async fn test(op: Operator) -> Result<()> { + /// let mut entries = op.lister_with("path/to/dir/").version(true).await?; + /// # Ok(()) + /// # } + /// ``` + /// /// # Examples /// /// ## List all files recursively From 20e669c41405fb60fd615e01eff8a6b198c78196 Mon Sep 17 00:00:00 2001 From: meteorgan Date: Tue, 26 Nov 2024 17:51:23 +0800 Subject: [PATCH 2/2] fix docs --- core/src/types/operator/operator.rs | 42 +++++++++++------------------ 1 file changed, 15 insertions(+), 27 deletions(-) diff --git a/core/src/types/operator/operator.rs b/core/src/types/operator/operator.rs index d81fed53e675..83a7877e716e 100644 --- a/core/src/types/operator/operator.rs +++ b/core/src/types/operator/operator.rs @@ -249,10 +249,9 @@ impl Operator { /// /// Set `version` for this `stat` request. /// - /// This feature can be used to retrieve the file metadata that matches a specified version. + /// This feature can be used to retrieve the metadata of a specific version of the given path /// - /// If file exists, but the version doesn't match, an error with kind [`ErrorKind::NotFound`] - /// will be returned. + /// If the version doesn't exist, an error with kind [`ErrorKind::NotFound`] will be returned. /// /// ```no_run /// # use opendal::Result; @@ -570,11 +569,9 @@ impl Operator { /// /// Set `version` for this `read` request. /// - /// By default, OpenDAL reads a file using the current version. By setting the `version`, OpenDAL will read - /// the file with the specified version. + /// This feature can be used to retrieve the data of a specified version of the given path. /// - /// If the file exists, but the version doesn't match, an error with kind [`ErrorKind::NotFound`] - /// will be returned. + /// If the version doesn't exist, an error with kind [`ErrorKind::NotFound`] will be returned. /// /// ```no_run /// # use opendal::Result; @@ -709,11 +706,9 @@ impl Operator { /// /// Set `version` for this `reader`. /// - /// By default, OpenDAL reads a file using the current version. By setting the `version`, OpenDAL will read - /// the file with the specified version. + /// This feature can be used to retrieve the data of a specified version of the given path. /// - /// If the file exists, but the version doesn't match, an error with kind [`ErrorKind::NotFound`] - /// will be returned. + /// If the version doesn't exist, an error with kind [`ErrorKind::NotFound`] will be returned. /// /// ```no_run /// # use opendal::Result; @@ -1546,13 +1541,9 @@ impl Operator { /// /// Set `version` for this `delete` request. /// - /// If `versioning` is not enabled, a `delete` request will permanently remove the file. - /// - /// when `versioning` is enabled, a simple `delete` request won't permanently remove the file, - /// it can still be accessed using its version. - /// By setting the `version`, OpenDAL will permanently remove the file with the specified version. + /// remove a specific version of the given path. /// - /// If the file exists, but the version doesn't match, OpenDAL will not return errors. + /// If the version doesn't exist, OpenDAL will not return errors. /// /// ```no_run /// # use opendal::Result; @@ -1868,14 +1859,13 @@ impl Operator { /// # Ok(()) /// # } /// ``` - /// ## `version` /// - /// Specify whether to list all object versions or not + /// ## `version` /// - /// if `version` is not set, or is set to false, only the active files with the current version will be returned. + /// Specify whether to list files along with all their versions /// - /// when `version` is set to true and the backend service has `versioning` enabled, all object versions will be returned. - /// if `versioning` is not enabled, an error with kind [`ErrorKind::Unsupported`] will be returned. + /// if `version` is enabled, all file versions will be returned; otherwise, + /// only the current files will be returned. /// /// ```no_run /// # use opendal::Result; @@ -2038,12 +2028,10 @@ impl Operator { /// /// ## `version` /// - /// Specify whether to list all object versions or not - /// - /// if `version` is not set, or is set to false, only the active files with the current version will be returned. + /// Specify whether to list files along with all their versions /// - /// when `version` is set to true and the backend service has `versioning` enabled, all object versions will be returned. - /// if `versioning` is not enabled, an error with kind [`ErrorKind::Unsupported`] will be returned. + /// if `version` is enabled, all file versions will be returned; otherwise, + /// only the current files will be returned. /// /// ```no_run /// # use opendal::Result;