docs(integrations/cloudfilter): improve docs and examples

integrations/cloudfilter/Cargo.toml

@@ -26,6 +26,9 @@ repository = "https://github.com/apache/opendal"
 rust-version = "1.75"
 version = "0.0.0"
 
+[package.metadata.docs.rs]
+default-target = "x86_64-pc-windows-msvc"
+
 [dependencies]
 anyhow = "1.0.86"
 bincode = "1.3.3"

integrations/cloudfilter/README.md

@@ -1,7 +1,82 @@
 # Apache OpenDAL™ Cloud Filter Integration
 
+[![Build Status]][actions] [![Latest Version]][crates.io] [![Crate Downloads]][crates.io] [![chat]][discord]
+
+[build status]: https://img.shields.io/github/actions/workflow/status/apache/opendal/test_behavior_integration_cloudfilter.yml?branch=main
+[actions]: https://github.com/apache/opendal/actions?query=branch%3Amain
+[latest version]: https://img.shields.io/crates/v/cloudfilter_opendal.svg
+[crates.io]: https://crates.io/crates/cloudfilter_opendal
+[crate downloads]: https://img.shields.io/crates/d/cloudfilter_opendal.svg
+[chat]: https://img.shields.io/discord/1081052318650339399
+[discord]: https://opendal.apache.org/discord
+
 `cloudfilter_opendal` integrates OpenDAL with [cloud sync engines](https://learn.microsoft.com/en-us/windows/win32/cfapi/build-a-cloud-file-sync-engine). It provides a way to access various cloud storage on Windows.
 
+Note that `cloudfilter_opendal` is a read-only service, and it is not recommended to use it in production.
+
+## Example
+
+```rust
+use anyhow::Result;
+use cloud_filter::root::PopulationType;
+use cloud_filter::root::SecurityId;
+use cloud_filter::root::Session;
+use cloud_filter::root::SyncRootIdBuilder;
+use cloud_filter::root::SyncRootInfo;
+use opendal::services;
+use opendal::Operator;
+use tokio::runtime::Handle;
+use tokio::signal;
+
+#[tokio::main]
+async fn main() -> Result<()> {
+    // Create any service desired
+    let op = Operator::from_iter::<services::S3>([
+        ("bucket".to_string(), "my_bucket".to_string()),
+        ("access_key".to_string(), "my_access_key".to_string()),
+        ("secret_key".to_string(), "my_secret_key".to_string()),
+        ("endpoint".to_string(), "my_endpoint".to_string()),
+        ("region".to_string(), "my_region".to_string()),
+    ])?
+    .finish();
+
+    let client_path = std::env::var("CLIENT_PATH").expect("$CLIENT_PATH is set");
+
+    // Create a sync root id
+    let sync_root_id = SyncRootIdBuilder::new("cloudfilter_opendal")
+        .user_security_id(SecurityId::current_user()?)
+        .build();
+
+    // Register the sync root if not exists
+    if !sync_root_id.is_registered()? {
+        sync_root_id.register(
+            SyncRootInfo::default()
+                .with_display_name("OpenDAL Cloud Filter")
+                .with_population_type(PopulationType::Full)
+                .with_icon("shell32.dll,3")
+                .with_version("1.0.0")
+                .with_recycle_bin_uri("http://cloudmirror.example.com/recyclebin")?
+                .with_path(&client_path)?,
+        )?;
+    }
+
+    let handle = Handle::current();
+    let connection = Session::new().connect_async(
+        &client_path,
+        cloudfilter_opendal::CloudFilter::new(op, client_path.clone().into()),
+        move |f| handle.block_on(f),
+    )?;
+
+    signal::ctrl_c().await?;
+
+    // Drop the connection before unregister the sync root
+    drop(connection);
+    sync_root_id.unregister()?;
+
+    Ok(())
+}
+```
+
 ## Branding
 
 The first and most prominent mentions must use the full form: **Apache OpenDAL™** of the name for any individual usage (webpage, handout, slides, etc.) Depending on the context and writing style, you should use the full form of the name sufficiently often to ensure that readers clearly understand the association of both the OpenDAL project and the OpenDAL software product to the ASF as the parent organization.

integrations/cloudfilter/examples/readonly.rs

@@ -1,4 +1,4 @@
-use std::{env, path::PathBuf};
+use std::env;
 
 use cloud_filter::root::{
     HydrationType, PopulationType, SecurityId, Session, SyncRootIdBuilder, SyncRootInfo,
@@ -45,8 +45,8 @@ async fn main() {
     let connection = Session::new()
         .connect_async(
             &client_path,
-            cloudfilter_opendal::CloudFilter::new(op, PathBuf::from(&client_path)),
-            move |f| handle.clone().block_on(f),
+            cloudfilter_opendal::CloudFilter::new(op, client_path.clone().into()),
+            move |f| handle.block_on(f),
         )
         .expect("create session");
 

integrations/cloudfilter/src/lib.rs

@@ -15,6 +15,74 @@
 // specific language governing permissions and limitations
 // under the License.
 
+//! `cloudfilter_opendal` integrates OpenDAL with [cloud sync engines](https://learn.microsoft.com/en-us/windows/win32/cfapi/build-a-cloud-file-sync-engine).
+//! It provides a way to access various cloud storage on Windows.
+//!
+//! Note that `cloudfilter_opendal` is a read-only service, and it is not recommended to use it in production.
+//! 
+//! # Example
+//! 
+//! ```no_run
+//! use anyhow::Result;
+//! use cloud_filter::root::PopulationType;
+//! use cloud_filter::root::SecurityId;
+//! use cloud_filter::root::Session;
+//! use cloud_filter::root::SyncRootIdBuilder;
+//! use cloud_filter::root::SyncRootInfo;
+//! use opendal::services;
+//! use opendal::Operator;
+//! use tokio::runtime::Handle;
+//! use tokio::signal;
+//! 
+//! #[tokio::main]
+//! async fn main() -> Result<()> {
+//!     // Create any service desired
+//!     let op = Operator::from_iter::<services::S3>([
+//!         ("bucket".to_string(), "my_bucket".to_string()),
+//!         ("access_key".to_string(), "my_access_key".to_string()),
+//!         ("secret_key".to_string(), "my_secret_key".to_string()),
+//!         ("endpoint".to_string(), "my_endpoint".to_string()),
+//!         ("region".to_string(), "my_region".to_string()),
+//!     ])?
+//!     .finish();
+//! 
+//!     let client_path = std::env::var("CLIENT_PATH").expect("$CLIENT_PATH is set");
+//! 
+//!     // Create a sync root id
+//!     let sync_root_id = SyncRootIdBuilder::new("cloudfilter_opendal")
+//!         .user_security_id(SecurityId::current_user()?)
+//!         .build();
+//! 
+//!     // Register the sync root if not exists
+//!     if !sync_root_id.is_registered()? {
+//!         sync_root_id.register(
+//!             SyncRootInfo::default()
+//!                 .with_display_name("OpenDAL Cloud Filter")
+//!                 .with_population_type(PopulationType::Full)
+//!                 .with_icon("shell32.dll,3")
+//!                 .with_version("1.0.0")
+//!                 .with_recycle_bin_uri("http://cloudmirror.example.com/recyclebin")?
+//!                 .with_path(&client_path)?,
+//!         )?;
+//!     }
+//! 
+//!     let handle = Handle::current();
+//!     let connection = Session::new().connect_async(
+//!         &client_path,
+//!         cloudfilter_opendal::CloudFilter::new(op, client_path.clone().into()),
+//!         move |f| handle.block_on(f),
+//!     )?;
+//! 
+//!     signal::ctrl_c().await?;
+//! 
+//!     // Drop the connection before unregister the sync root
+//!     drop(connection);
+//!     sync_root_id.unregister()?;
+//! 
+//!     Ok(())
+//! }
+//! ``````
+
 mod file;
 
 use std::{
@@ -37,12 +105,14 @@ use opendal::{Entry, Metakey, Operator};
 
 const BUF_SIZE: usize = 65536;
 
+/// CloudFilter is a adapter that adapts Windows cloud sync engines.
 pub struct CloudFilter {
     op: Operator,
     root: PathBuf,
 }
 
 impl CloudFilter {
+    /// Create a new CloudFilter.
     pub fn new(op: Operator, root: PathBuf) -> Self {
         Self { op, root }
     }