docs: Add docs for azblob's public structs

.github/workflows/service_test_azblob.yml

@@ -28,7 +28,6 @@ jobs:
                 --name test \
                 --connection-string "DefaultEndpointsProtocol=http;AccountName=devstoreaccount1;AccountKey=Eby8vdM02xNOcqFlqUwJPLlmEtlCDXJ1OUzFT50uSRZ6IFsuFq2UVErCz4I6tq/K1SZFPTOtr/KBHBeksoGMGw==;BlobEndpoint=http://127.0.0.1:10000/devstoreaccount1;"
 
-
       - name: Test
         shell: bash
         run: cargo test azblob --all-features -- --nocapture

README.md

@@ -21,8 +21,9 @@ OpenDAL is in **alpha** stage and has been early adopted by [databend](https://g
 
 ## Supported Services
 
+- [azblob](https://docs.rs/opendal/latest/opendal/services/azblob/index.html): Azure Storage Blob services.
 - [fs](https://docs.rs/opendal/latest/opendal/services/fs/index.html): POSIX alike file system.
-- [memory](https://docs.rs/opendal/latest/opendal/services/memory/index.html): In memory backend support.
+- [memory](https://docs.rs/opendal/latest/opendal/services/memory/index.html): In memory backend.
 - [s3](https://docs.rs/opendal/latest/opendal/services/s3/index.html): AWS S3 alike services.
 
 ## Quickstart

src/lib.rs

@@ -18,6 +18,7 @@
 //!
 //! | Services | Description |
 //! | -------- | ----------- |
+//! | [azblob][crate::services::azblob] | Azure Storage Blob services. |
 //! | [fs][crate::services::fs] | POSIX alike file system. |
 //! | [memory][crate::services::memory] | In memory backend support. |
 //! | [s3][crate::services::s3] | AWS S3 alike services. |

src/services/azblob/backend.rs

@@ -62,8 +62,9 @@ use crate::BytesWriter;
 use crate::ObjectMode;
 use crate::ObjectStreamer;
 
-pub const X_MS_BLOB_TYPE: &str = "x-ms-blob-type";
+const X_MS_BLOB_TYPE: &str = "x-ms-blob-type";
 
+/// Builder for azblob services
 #[derive(Default, Clone)]
 pub struct Builder {
     root: Option<String>,
@@ -93,6 +94,9 @@ impl Debug for Builder {
 }
 
 impl Builder {
+    /// Set root of this backend.
+    ///
+    /// All operations will happen under this root.
     pub fn root(&mut self, root: &str) -> &mut Self {
         if !root.is_empty() {
             self.root = Some(root.to_string())
@@ -101,25 +105,43 @@ impl Builder {
         self
     }
 
+    /// Set container name of this backend.
     pub fn container(&mut self, container: &str) -> &mut Self {
         self.container = container.to_string();
 
         self
     }
+
+    /// Set endpoint of this backend.
+    ///
+    /// Endpoint must be full uri, e.g.
+    ///
+    /// - Azblob: `https://accountname.blob.core.windows.net`
+    /// - Azurite: `http://127.0.0.1:10000/devstoreaccount1`
     pub fn endpoint(&mut self, endpoint: &str) -> &mut Self {
         if !endpoint.is_empty() {
             self.endpoint = Some(endpoint.to_string());
         }
 
         self
     }
+
+    /// Set account_name of this backend.
+    ///
+    /// - If account_name is set, we will take user's input first.
+    /// - If not, we will try to load it from environment.
     pub fn account_name(&mut self, account_name: &str) -> &mut Self {
         if !account_name.is_empty() {
             self.account_name = Some(account_name.to_string());
         }
 
         self
     }
+
+    /// Set account_key of this backend.
+    ///
+    /// - If account_key is set, we will take user's input first.
+    /// - If not, we will try to load it from environment.
     pub fn account_key(&mut self, account_key: &str) -> &mut Self {
         if !account_key.is_empty() {
             self.account_key = Some(account_key.to_string());
@@ -128,6 +150,7 @@ impl Builder {
         self
     }
 
+    /// Consume builder to build an azblob backend.
     pub async fn finish(&mut self) -> Result<Arc<dyn Accessor>> {
         info!("backend build started: {:?}", &self);
 
@@ -163,9 +186,13 @@ impl Builder {
         debug!("backend use container {}", &container);
 
         let endpoint = match &self.endpoint {
-            Some(endpoint) => endpoint.clone(),
-            None => "https://blob.core.windows.net".to_string(),
-        };
+            Some(endpoint) => Ok(endpoint.clone()),
+            None => Err(other(BackendError::new(
+                HashMap::from([("endpoint".to_string(), "".to_string())]),
+                anyhow!("endpoint is empty"),
+            ))),
+        }?;
+        debug!("backend use endpoint {}", &container);
 
         let context = HashMap::from([
             ("container".to_string(), container.to_string()),
@@ -195,7 +222,7 @@ impl Builder {
         }))
     }
 }
-
+/// Backend for azblob services.
 #[derive(Debug, Clone)]
 pub struct Backend {
     container: String,
@@ -233,6 +260,7 @@ impl Backend {
         }
     }
 }
+
 #[async_trait]
 impl Accessor for Backend {
     #[trace("read")]

src/services/azblob/mod.rs

@@ -11,6 +11,67 @@
 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 // See the License for the specific language governing permissions and
 // limitations under the License.
+
+//! Azure Storage Blob services support.
+//!
+//! # Example
+//!
+//! This example works on [Azurite](https://github.com/Azure/Azurite) for local developments.
+//!
+//! ## Start local blob service
+//!
+//! ```shell
+//! docker run -p 10000:10000 mcr.microsoft.com/azure-storage/azurite
+//! az storage container create --name test --connection-string "DefaultEndpointsProtocol=http;AccountName=devstoreaccount1;AccountKey=Eby8vdM02xNOcqFlqUwJPLlmEtlCDXJ1OUzFT50uSRZ6IFsuFq2UVErCz4I6tq/K1SZFPTOtr/KBHBeksoGMGw==;BlobEndpoint=http://127.0.0.1:10000/devstoreaccount1;"
+//! ```
+//!
+//! ## Init OpenDAL Operator
+//!
+//! ```no_run
+//! use std::sync::Arc;
+//!
+//! use anyhow::Result;
+//! use opendal::services::azblob;
+//! use opendal::services::azblob::Builder;
+//! use opendal::Accessor;
+//! use opendal::Object;
+//! use opendal::Operator;
+//!
+//! #[tokio::main]
+//! async fn main() -> Result<()> {
+//!     // Create azblob backend builder.
+//!     let mut builder: Builder = azblob::Backend::build();
+//!     // Set the root for azblob, all operations will happen under this root.
+//!     //
+//!     // NOTE: the root must be absolute path.
+//!     builder.root("/path/to/dir");
+//!     // Set the container name, this is required.
+//!     builder.container("test");
+//!     // Set the endpoint, this is required.
+//!     //
+//!     // For examples:
+//!     // - "http://127.0.0.1:10000/devstoreaccount1"
+//!     // - "https://accountname.blob.core.windows.net"
+//!     builder.endpoint("http://127.0.0.1:10000/devstoreaccount1");
+//!     // Set the account_name and account_key.
+//!     //
+//!     // OpenDAL will try load credential from the env.
+//!     // If credential not set and no valid credential in env, OpenDAL will
+//!     // send request without signing like anonymous user.
+//!     builder.account_name("devstoreaccount1");
+//!     builder.account_key("Eby8vdM02xNOcqFlqUwJPLlmEtlCDXJ1OUzFT50uSRZ6IFsuFq2UVErCz4I6tq/K1SZFPTOtr/KBHBeksoGMGw==");
+//!     // Build the `Accessor`.
+//!     let accessor: Arc<dyn Accessor> = builder.finish().await?;
+//!
+//!     // `Accessor` provides the low level APIs, we will use `Operator` normally.
+//!     let op: Operator = Operator::new(accessor);
+//!
+//!     // Create an object handle to start operation on object.
+//!     let _: Object = op.object("test_file");
+//!
+//!     Ok(())
+//! }
+//! ```
 mod backend;
 pub use backend::Backend;
 pub use backend::Builder;

src/services/azblob/object_stream.rs

@@ -42,11 +42,13 @@ pub struct AzblobObjectStream {
     done: bool,
     state: State,
 }
+
 enum State {
     Idle,
     Sending(BoxFuture<'static, Result<bytes::Bytes>>),
     Listing((Output, usize, usize)),
 }
+
 impl AzblobObjectStream {
     pub fn new(backend: Backend, path: String) -> Self {
         Self {
@@ -177,11 +179,13 @@ struct Blobs {
     blob: Vec<Blob>,
     blob_prefix: Option<Vec<BlobPrefix>>,
 }
+
 #[derive(Default, Debug, Deserialize)]
 #[serde(default, rename_all = "PascalCase")]
 struct BlobPrefix {
     name: String,
 }
+
 #[derive(Default, Debug, Deserialize)]
 #[serde(default, rename_all = "PascalCase")]
 struct Blob {
@@ -199,13 +203,13 @@ struct Properties {
 #[cfg(test)]
 mod tests {
     use super::*;
+
     #[test]
     fn test_parse_xml() {
         let bs = bytes::Bytes::from(
-            r#" 
-            \xef\xbb\xbf
+            r#"
             <?xml version="1.0" encoding="utf-8"?>
-            <EnumerationResults ServiceEndpoint="https://d2lark.blob.core.windows.net/" ContainerName="myazurebucket">
+            <EnumerationResults ServiceEndpoint="https://test.blob.core.windows.net/" ContainerName="myazurebucket">
                 <Prefix>dir1/</Prefix>
                 <Delimiter>/</Delimiter>
                 <Blobs>