docs: Add docs of options for xxx_with APIs (#4099)

* docs: Add options for xxx_with APIs Signed-off-by: Xuanwo <[email protected]> * Update opendal.h Signed-off-by: Xuanwo <[email protected]> --------- Signed-off-by: Xuanwo <[email protected]>
apache · Jan 30, 2024 · 953d472 · 953d472
1 parent 48383aa
commit 953d472
Show file tree

Hide file tree

Showing 36 changed files with 740 additions and 203 deletions.
diff --git a/bin/ofs/Cargo.toml b/bin/ofs/Cargo.toml
@@ -30,20 +30,20 @@ repository.workspace = true
 rust-version.workspace = true
 
 [dependencies]
+anyhow = "1"
 async-trait = "0.1.75"
+clap = { version = "4.4.18", features = ["derive", "env"] }
+env_logger = "0.10"
 fuse3 = { "version" = "0.6.1", "features" = ["tokio-runtime", "unprivileged"] }
 futures-util = "0.3.30"
 libc = "0.2.151"
 log = "0.4.20"
-anyhow = "1"
+nix = { version = "0.27.1", features = ["user"] }
+opendal.workspace = true
 tokio = { version = "1.34", features = [
   "fs",
   "macros",
   "rt-multi-thread",
   "io-std",
 ] }
-nix = { version = "0.27.1", features = ["user"] }
-env_logger = "0.10"
-clap = { version = "4.4.18", features = ["derive", "env"] }
 url = "2.5.0"
-opendal.workspace = true
diff --git a/bindings/c/include/opendal.h b/bindings/c/include/opendal.h
@@ -120,7 +120,6 @@ typedef struct BlockingLister BlockingLister;
  *
  * Some services like s3, gcs doesn't have native blocking supports, we can use [`layers::BlockingLayer`]
  * to wrap the async operator to make it blocking.
- *
  * # use anyhow::Result;
  * use opendal::layers::BlockingLayer;
  * use opendal::services::S3;

diff --git a/bindings/java/Cargo.toml b/bindings/java/Cargo.toml
@@ -98,8 +98,8 @@ services-all = [
 # Default services provided by opendal.
 services-azblob = ["opendal/services-azblob"]
 services-azdls = ["opendal/services-azdls"]
-services-cos = ["opendal/services-cos"]
 services-chainsafe = ["opendal/services-chainsafe"]
+services-cos = ["opendal/services-cos"]
 services-fs = ["opendal/services-fs"]
 services-gcs = ["opendal/services-gcs"]
 services-ghac = ["opendal/services-ghac"]

diff --git a/bindings/nodejs/Cargo.toml b/bindings/nodejs/Cargo.toml
@@ -93,8 +93,8 @@ services-all = [
 # Default services provided by opendal.
 services-azblob = ["opendal/services-azblob"]
 services-azdls = ["opendal/services-azdls"]
-services-cos = ["opendal/services-cos"]
 services-chainsafe = ["opendal/services-chainsafe"]
+services-cos = ["opendal/services-cos"]
 services-fs = ["opendal/services-fs"]
 services-gcs = ["opendal/services-gcs"]
 services-ghac = ["opendal/services-ghac"]

diff --git a/bindings/php/Cargo.toml b/bindings/php/Cargo.toml
@@ -17,8 +17,8 @@
 
 [package]
 name = "opendal-php"
-version = "0.1.0"
 publish = false
+version = "0.1.0"
 
 authors = ["Apache OpenDAL <[email protected]>"]
 edition = "2021"

diff --git a/bindings/python/Cargo.toml b/bindings/python/Cargo.toml
@@ -95,8 +95,8 @@ services-all = [
 # Default services provided by opendal.
 services-azblob = ["opendal/services-azblob"]
 services-azdls = ["opendal/services-azdls"]
-services-cos = ["opendal/services-cos"]
 services-chainsafe = ["opendal/services-chainsafe"]
+services-cos = ["opendal/services-cos"]
 services-fs = ["opendal/services-fs"]
 services-gcs = ["opendal/services-gcs"]
 services-ghac = ["opendal/services-ghac"]

diff --git a/bindings/ruby/Cargo.toml b/bindings/ruby/Cargo.toml
@@ -17,8 +17,8 @@
 
 [package]
 name = "opendal-ruby"
-version = "0.1.0"
 publish = false
+version = "0.1.0"
 
 authors = ["Apache OpenDAL <[email protected]>"]
 edition = "2021"

diff --git a/core/Cargo.toml b/core/Cargo.toml
@@ -111,8 +111,8 @@ layers-await-tree = ["dep:await-tree"]
 # Enable layers async-backtrace support.
 layers-async-backtrace = ["dep:async-backtrace"]
 # Enable dtrace support.
-layers-dtrace=["dep:probe"]
 layers-blocking = ["internal-tokio-rt"]
+layers-dtrace = ["dep:probe"]
 
 services-alluxio = []
 services-atomicserver = ["dep:atomic_lib"]
@@ -156,9 +156,9 @@ services-gridfs = ["dep:mongodb"]
 services-hdfs = ["dep:hdrs"]
 services-http = []
 services-huggingface = []
+services-icloud = ["internal-path-cache"]
 services-ipfs = ["dep:prost"]
 services-ipmfs = []
-services-icloud = ["internal-path-cache"]
 services-koofr = []
 services-libsql = ["dep:hrana-client-proto"]
 services-memcached = ["dep:bb8"]
@@ -202,11 +202,11 @@ services-vercel-artifacts = []
 # Deprecated
 # wasabi services support has been removed.
 # We will remove this feature in the next version.
+services-hdfs-native = ["hdfs-native"]
 services-wasabi = []
 services-webdav = []
 services-webhdfs = []
 services-yandex-disk = []
-services-hdfs-native = ["hdfs-native"]
 
 internal-tokio-rt = ["tokio/rt-multi-thread"]
 
@@ -341,7 +341,7 @@ suppaftp = { version = "5.3.1", default-features = false, features = [
 # for services-tikv
 tikv-client = { version = "0.3.0", optional = true, default-features = false }
 # for services-hdfs-native
-hdfs-native = { version = "0.6.0", optional = true}
+hdfs-native = { version = "0.6.0", optional = true }
 
 # Layers
 # for layers-async-backtrace

diff --git a/core/src/layers/dtrace.rs b/core/src/layers/dtrace.rs
@@ -15,19 +15,21 @@
 // specific language governing permissions and limitations
 // under the License.
 
-use crate::raw::Accessor;
-use crate::raw::*;
-use crate::*;
-use async_trait::async_trait;
-use bytes::Bytes;
-use probe::probe_lazy;
 use std::ffi::CString;
 use std::fmt::Debug;
 use std::fmt::Formatter;
 use std::io;
 use std::task::Context;
 use std::task::Poll;
 
+use async_trait::async_trait;
+use bytes::Bytes;
+use probe::probe_lazy;
+
+use crate::raw::Accessor;
+use crate::raw::*;
+use crate::*;
+
 /// Support User Statically-Defined Tracing(aka USDT) on Linux
 ///
 /// This layer is an experimental feature, it will be enabled by `features = ["layers-dtrace"]` in Cargo.toml.
@@ -113,11 +115,10 @@ use std::task::Poll;
 ///
 /// Example:
 /// ```
-///
 /// use anyhow::Result;
+/// use opendal::layers::DTraceLayer;
 /// use opendal::services::Fs;
 /// use opendal::Operator;
-/// use opendal::layers::DTraceLayer;
 ///
 /// #[tokio::main]
 /// async fn main() -> Result<()> {
@@ -126,10 +127,12 @@ use std::task::Poll;
 ///     builder.root("/tmp");
 ///
 ///     // `Accessor` provides the low level APIs, we will use `Operator` normally.
-///     let op: Operator = Operator::new(builder)?.layer(DtraceLayer::default()).finish();
-///     
-///     let path="/tmp/test.txt";
-///     for _ in 1..100000{
+///     let op: Operator = Operator::new(builder)?
+///         .layer(DtraceLayer::default())
+///         .finish();
+///
+///     let path = "/tmp/test.txt";
+///     for _ in 1..100000 {
 ///         let bs = vec![0; 64 * 1024 * 1024];
 ///         op.write(path, bs).await?;
 ///         op.read(path).await?;

diff --git a/core/src/layers/timeout.rs b/core/src/layers/timeout.rs
@@ -18,8 +18,9 @@
 use std::future::Future;
 use std::io::SeekFrom;
 use std::pin::Pin;
+use std::task::ready;
+use std::task::Context;
 use std::task::Poll;
-use std::task::{ready, Context};
 use std::time::Duration;
 
 use async_trait::async_trait;
@@ -57,18 +58,21 @@ use crate::*;
 /// operations, 3 seconds timeout for all io operations.
 ///
 /// ```
+/// use std::time::Duration;
+///
 /// use anyhow::Result;
 /// use opendal::layers::TimeoutLayer;
 /// use opendal::services;
 /// use opendal::Operator;
 /// use opendal::Scheme;
-/// use std::time::Duration;
 ///
 /// let _ = Operator::new(services::Memory::default())
 ///     .expect("must init")
-///     .layer(TimeoutLayer::default()
-///         .with_timeout(Duration::from_secs(10))
-///         .with_io_timeout(Duration::from_secs(3)))
+///     .layer(
+///         TimeoutLayer::default()
+///             .with_timeout(Duration::from_secs(10))
+///             .with_io_timeout(Duration::from_secs(3)),
+///     )
 ///     .finish();
 /// ```
 ///
@@ -368,17 +372,22 @@ impl<R: oio::List> oio::List for TimeoutWrapper<R> {
 
 #[cfg(test)]
 mod tests {
-    use crate::layers::{TimeoutLayer, TypeEraseLayer};
-    use crate::raw::oio::ReadExt;
-    use crate::raw::*;
-    use crate::*;
-    use async_trait::async_trait;
-    use bytes::Bytes;
     use std::io::SeekFrom;
     use std::sync::Arc;
-    use std::task::{Context, Poll};
+    use std::task::Context;
+    use std::task::Poll;
     use std::time::Duration;
-    use tokio::time::{sleep, timeout};
+
+    use async_trait::async_trait;
+    use bytes::Bytes;
+    use tokio::time::sleep;
+    use tokio::time::timeout;
+
+    use crate::layers::TimeoutLayer;
+    use crate::layers::TypeEraseLayer;
+    use crate::raw::oio::ReadExt;
+    use crate::raw::*;
+    use crate::*;
 
     #[derive(Debug, Clone, Default)]
     struct MockService;

diff --git a/core/src/raw/oio/write/block_write.rs b/core/src/raw/oio/write/block_write.rs
@@ -326,14 +326,20 @@ where
 
 #[cfg(test)]
 mod tests {
-    use super::*;
-    use crate::raw::oio::{StreamExt, WriteBuf, WriteExt};
-    use bytes::Bytes;
-    use pretty_assertions::assert_eq;
-    use rand::{thread_rng, Rng, RngCore};
     use std::collections::HashMap;
     use std::sync::Mutex;
 
+    use bytes::Bytes;
+    use pretty_assertions::assert_eq;
+    use rand::thread_rng;
+    use rand::Rng;
+    use rand::RngCore;
+
+    use super::*;
+    use crate::raw::oio::StreamExt;
+    use crate::raw::oio::WriteBuf;
+    use crate::raw::oio::WriteExt;
+
     struct TestWrite {
         length: u64,
         bytes: HashMap<Uuid, Bytes>,

diff --git a/core/src/raw/oio/write/multipart_write.rs b/core/src/raw/oio/write/multipart_write.rs
@@ -404,11 +404,15 @@ where
 
 #[cfg(test)]
 mod tests {
+    use std::sync::Mutex;
+
+    use pretty_assertions::assert_eq;
+    use rand::thread_rng;
+    use rand::Rng;
+    use rand::RngCore;
+
     use super::*;
     use crate::raw::oio::WriteExt;
-    use pretty_assertions::assert_eq;
-    use rand::{thread_rng, Rng, RngCore};
-    use std::sync::Mutex;
 
     struct TestWrite {
         upload_id: String,

diff --git a/core/src/raw/oio/write/range_write.rs b/core/src/raw/oio/write/range_write.rs
@@ -354,13 +354,17 @@ impl<W: RangeWrite> oio::Write for RangeWriter<W> {
 
 #[cfg(test)]
 mod tests {
-    use super::*;
-    use crate::raw::oio::WriteExt;
-    use pretty_assertions::assert_eq;
-    use rand::{thread_rng, Rng, RngCore};
     use std::collections::HashSet;
     use std::sync::Mutex;
 
+    use pretty_assertions::assert_eq;
+    use rand::thread_rng;
+    use rand::Rng;
+    use rand::RngCore;
+
+    use super::*;
+    use crate::raw::oio::WriteExt;
+
     struct TestWrite {
         length: u64,
         bytes: HashSet<u64>,

diff --git a/core/src/raw/path_cache.rs b/core/src/raw/path_cache.rs
@@ -15,12 +15,15 @@
 // specific language governing permissions and limitations
 // under the License.
 
-use crate::raw::*;
-use crate::*;
+use std::collections::VecDeque;
+
 use async_trait::async_trait;
 use moka::sync::Cache;
-use std::collections::VecDeque;
-use tokio::sync::{Mutex, MutexGuard};
+use tokio::sync::Mutex;
+use tokio::sync::MutexGuard;
+
+use crate::raw::*;
+use crate::*;
 
 /// The trait required for path cacher.
 #[cfg_attr(not(target_arch = "wasm32"), async_trait)]
@@ -191,10 +194,12 @@ impl<Q: PathQuery> PathCacher<Q> {
 
 #[cfg(test)]
 mod tests {
-    use crate::raw::{PathCacher, PathQuery};
-    use crate::*;
     use async_trait::async_trait;
 
+    use crate::raw::PathCacher;
+    use crate::raw::PathQuery;
+    use crate::*;
+
     struct TestQuery {}
 
     #[async_trait]

diff --git a/core/src/raw/tokio_util.rs b/core/src/raw/tokio_util.rs
@@ -15,7 +15,8 @@
 // specific language governing permissions and limitations
 // under the License.
 
-use crate::{Error, ErrorKind};
+use crate::Error;
+use crate::ErrorKind;
 
 /// Parse tokio error into opendal::Error.
 pub fn new_task_join_error(e: tokio::task::JoinError) -> Error {

diff --git a/core/src/services/dropbox/builder.rs b/core/src/services/dropbox/builder.rs
@@ -15,14 +15,14 @@
 // specific language governing permissions and limitations
 // under the License.
 
-use serde::Deserialize;
 use std::collections::HashMap;
 use std::fmt::Debug;
 use std::fmt::Formatter;
 use std::sync::Arc;
 
 use chrono::DateTime;
 use chrono::Utc;
+use serde::Deserialize;
 use tokio::sync::Mutex;
 
 use super::backend::DropboxBackend;

diff --git a/core/src/services/gdrive/builder.rs b/core/src/services/gdrive/builder.rs
@@ -27,10 +27,13 @@ use serde::Deserialize;
 use tokio::sync::Mutex;
 
 use super::backend::GdriveBackend;
-use crate::raw::{normalize_root, PathCacher};
-use crate::raw::{ConfigDeserializer, HttpClient};
+use crate::raw::normalize_root;
+use crate::raw::ConfigDeserializer;
+use crate::raw::HttpClient;
+use crate::raw::PathCacher;
+use crate::services::gdrive::core::GdriveCore;
+use crate::services::gdrive::core::GdrivePathQuery;
 use crate::services::gdrive::core::GdriveSigner;
-use crate::services::gdrive::core::{GdriveCore, GdrivePathQuery};
 use crate::Scheme;
 use crate::*;