opendal 0.1.8 → 0.1.9

data/core/core/src/lib.rs

@@ -18,142 +18,9 @@
 #![doc(
     html_logo_url = "https://raw.githubusercontent.com/apache/opendal/main/website/static/img/logo.svg"
 )]
+#![doc = include_str!("../README.md")]
 #![cfg_attr(docsrs, feature(doc_cfg))]
-//! Apache OpenDAL™ is an Open Data Access Layer that enables seamless interaction with diverse storage services.
-//!
-//! OpenDAL's development is guided by its vision of **One Layer, All Storage** and its core principles: **Open Community**, **Solid Foundation**, **Fast Access**, **Object Storage First**, and **Extensible Architecture**. Read the explained vision at [OpenDAL Vision](https://opendal.apache.org/vision).
-//!
-//! # Quick Start
-//!
-//! OpenDAL's API entry points are [`Operator`] and [`blocking::Operator`]. All
-//! public APIs are accessible through the operator. To utilize OpenDAL, you
-//! need to:
-//!
-//! - [Init a service](#init-a-service)
-//! - [Compose layers](#compose-layers)
-//! - [Use operator](#use-operator)
-//!
-//! ## Init a service
-//!
-//! The first step is to pick a service and init it with a builder. All supported
-//! services could be found at [`services`].
-//!
-//! Let's take [`services::Memory`] as an example:
-//!
-//! ```no_run
-//! use opendal_core::services;
-//! use opendal_core::Operator;
-//! use opendal_core::Result;
-//!
-//! fn main() -> Result<()> {
-//!     // Pick a builder and configure it.
-//!     let builder = services::Memory::default();
-//!
-//!     // Init an operator
-//!     let op = Operator::new(builder)?;
-//!     Ok(())
-//! }
-//! ```
-//!
-//! ## Compose layers
-//!
-//! The next setup is to compose layers. Layers are modules that provide extra
-//! features for every operation. All builtin layers could be found at [`layers`].
-//!
-//! Let's use [`layers::CapabilityOverrideLayer`] and a custom [`HttpTransporter`] as an example.
-//!
-//! ```no_run
-//! use opendal_core::layers::CapabilityOverrideLayer;
-//! use opendal_core::HttpTransporter;
-//! use opendal_core::OperationContext;
-//! use opendal_core::services;
-//! use opendal_core::Operator;
-//! use opendal_core::Result;
-//!
-//! #[tokio::main]
-//! async fn main() -> Result<()> {
-//!     // Pick a builder and configure it.
-//!     let builder = services::Memory::default();
-//!
-//!     // Init an operator
-//!     let transport = HttpTransporter::default();
-//!     let op = Operator::new(builder)?
-//!         // Replace the base HTTP transport.
-//!         .with_context(OperationContext::new().with_http_transport(transport))
-//!         .layer(CapabilityOverrideLayer::new(|cap| cap));
-//!
-//!     Ok(())
-//! }
-//! ```
-//!
-//! ## Use operator
-//!
-//! The final step is to use the operator. OpenDAL supports both async [`Operator`]
-//! and blocking [`blocking::Operator`]. Please pick the one that fits your use case.
-//!
-//! Every Operator API follows a consistent pattern. For example, consider the `read` operation:
-//!
-//! - [`Operator::read`]: Executes a read operation.
-//! - [`Operator::read_with`]: Executes a read operation with additional options using the builder pattern.
-//! - [`Operator::read_options`]: Executes a read operation with extra options provided via a [`options::ReadOptions`] struct.
-//! - [`Operator::reader`]: Creates a reader for streaming data, allowing for flexible access.
-//! - [`Operator::reader_with`]: Creates a reader with advanced options using the builder pattern.
-//! - [`Operator::reader_options`]: Creates a reader with extra options provided via a [`options::ReadOptions`] struct.
-//!
-//! The [`Reader`] created by [`Operator`] supports custom read control methods and can be converted
-//! into [`futures::AsyncRead`] or [`futures::Stream`] for broader ecosystem compatibility.
-//!
-//! ```no_run
-//! use opendal_core::options;
-//! use opendal_core::HttpTransporter;
-//! use opendal_core::OperationContext;
-//! use opendal_core::services;
-//! use opendal_core::Operator;
-//! use opendal_core::Result;
-//!
-//! #[tokio::main]
-//! async fn main() -> Result<()> {
-//!     // Pick a builder and configure it.
-//!     let builder = services::Memory::default();
-//!
-//!     // Init an operator
-//!     let transport = HttpTransporter::default();
-//!     let op = Operator::new(builder)?
-//!         // Replace the base HTTP transport.
-//!         .with_context(OperationContext::new().with_http_transport(transport));
-//!
-//!     // Fetch this file's metadata
-//!     let meta = op.stat("hello.txt").await?;
-//!     let length = meta.content_length();
-//!
-//!     // Read data from `hello.txt` with options.
-//!     let bs = op
-//!         .read_with("hello.txt")
-//!         .range(0..8 * 1024 * 1024)
-//!         .chunk(1024 * 1024)
-//!         .concurrent(4)
-//!         .await?;
-//!
-//!     // The same to:
-//!     let bs = op
-//!         .read_options("hello.txt", options::ReadOptions {
-//!             range: (0..8 * 1024 * 1024).into(),
-//!             chunk: Some(1024 * 1024),
-//!             concurrent: 4,
-//!             ..Default::default()
-//!         })
-//!         .await?;
-//!
-//!     Ok(())
-//! }
-//! ```
-//!
-//! # Useful Links
-//!
-//! - [Concept][crate::docs::concepts]
-//! - [Internals][crate::docs::internals]
-//! - [Performance Guide][crate::docs::performance]
-
+#![cfg_attr(docsrs, doc(auto_cfg))]
 // Make sure all our public APIs have docs.
 #![deny(missing_docs)]
 
@@ -164,8 +31,6 @@ pub use types::*;
 // Public modules, they will be accessed like `opendal::layers::Xxxx`
 #[cfg(feature = "blocking")]
 pub mod blocking;
-#[cfg(docsrs)]
-pub mod docs;
 pub mod layers;
 pub mod raw;
 pub mod services;

data/core/core/src/raw/accessor.rs

@@ -22,10 +22,10 @@ use std::sync::Arc;
 use crate::raw::*;
 use crate::*;
 
-/// Immutable identity facts for a storage service.
+/// Immutable identity and configuration for a storage service.
 ///
-/// Runtime resources and composed capabilities are kept outside this value so
-/// layers can replace them without mutating shared service identity.
+/// `ServiceInfo` excludes runtime resources and composed capabilities so that
+/// layers can replace them without mutating the shared service identity.
 #[derive(Clone, PartialEq, Eq, Hash)]
 pub struct ServiceInfo {
     scheme: &'static str,
@@ -44,7 +44,7 @@ impl Debug for ServiceInfo {
 }
 
 impl ServiceInfo {
-    /// Create a new service info value.
+    /// Create a new `ServiceInfo`.
     pub fn new(scheme: &'static str, root: impl AsRef<str>, name: impl AsRef<str>) -> Self {
         Self {
             scheme,
@@ -53,12 +53,12 @@ impl ServiceInfo {
         }
     }
 
-    /// Create a new service info value with only scheme.
+    /// Create a new `ServiceInfo` with only scheme.
     pub fn with_scheme(scheme: &'static str) -> Self {
         Self::new(scheme, "", "")
     }
 
-    /// Return a copy of this service info with a different root.
+    /// Return a copy of this `ServiceInfo` with a different root.
     pub fn with_root(&self, root: impl AsRef<str>) -> Self {
         Self {
             scheme: self.scheme,
@@ -67,17 +67,17 @@ impl ServiceInfo {
         }
     }
 
-    /// Scheme of backend.
+    /// Scheme of the service.
     pub fn scheme(&self) -> &'static str {
         self.scheme
     }
 
-    /// Root of backend, will be in format like `/path/to/dir/`.
+    /// Root of the service. Follows a format like `/path/to/dir/`.
     pub fn root(&self) -> Arc<str> {
         self.root.clone()
     }
 
-    /// Name of backend, could be empty if underlying backend doesn't have namespace concept.
+    /// Name of the service. This might be empty if the service has no namespace concept.
     ///
     /// For example:
     ///
@@ -90,18 +90,19 @@ impl ServiceInfo {
     }
 }
 
-/// Underlying trait of all storage services.
+/// Foundational trait for storage services.
 ///
-/// Every storage backend supported by OpenDAL implements [`Service`]. Backends
-/// must implement every operation so unsupported behavior is explicit at the
-/// implementation boundary.
+/// Every storage service (or backend) in OpenDAL implements [`Service`]. Services
+/// and layers must implement every operation in this trait and declare their
+/// capabilities. This allows callers to detect unsupported operations.
 ///
 /// # Operations
 ///
-/// - Paths passed into service operations are normalized by the operator.
-///   - `/` means the root path.
-///   - Paths ending with `/` are directory paths.
-///   - Other paths are file paths.
+/// - An operator normalizes paths before passing them to a `Service`. Relative to
+///   the configured `root`:
+///   - `/` represents the root.
+///   - A path ending with `/` represents a directory.
+///   - Any other path represents a file.
 /// - Services report their supported operation set through [`Service::capability`].
 /// - The [`OperationContext`] carries layer-composed runtime resources for each
 ///   operation.
@@ -117,13 +118,14 @@ pub trait Service: Send + Sync + Debug + Unpin + 'static {
     /// Copier returned by `copy`.
     type Copier: oio::Copy;
 
-    /// Return immutable identity facts for this service.
+    /// Return the immutable identity and configuration for this service.
     fn info(&self) -> ServiceInfo;
 
     /// Return the capability of this service stack.
     ///
-    /// Layers may transform capabilities, so callers should use this value for
-    /// the current stack instead of assuming the backend's native capability.
+    /// Layers may affect a service's capabilities, so callers should use this
+    /// value for the current stack instead of assuming the backend's native
+    /// capability.
     fn capability(&self) -> Capability;
 
     /// Invoke the `create` operation on the specified path.
@@ -411,7 +413,7 @@ impl<S: Service + ?Sized> ServiceDyn for S {
     }
 }
 
-/// Service is used behind a [`Servicer`] everywhere.
+/// Implement `Service` for type-erased services so they use the same API.
 impl<T: ServiceDyn + ?Sized> Service for Arc<T> {
     type Reader = oio::Reader;
     type Writer = oio::Writer;

data/core/core/src/raw/oio/buf/queue_buf.rs

@@ -24,8 +24,10 @@ use crate::*;
 
 /// QueueBuf is a queue of [`Buffer`].
 ///
-/// It's designed to allow storing multiple buffers without copying underlying bytes and consume them
-/// in order.
+/// QueueBuf allows:
+///
+/// - Storing multiple buffers without copying bytes.
+/// - Consuming buffers in order.
 ///
 /// QueueBuf mainly provides the following operations:
 ///

data/core/core/src/raw/oio/write/block_write.rs

@@ -58,11 +58,12 @@ use crate::*;
 /// - Block ID is generated by caller `BlockWrite` instead of services.
 /// - Complete block by an ordered block id list.
 pub trait BlockWrite: Send + Sync + Unpin + 'static {
-    /// write_once is used to write the data to underlying storage at once.
+    /// `write_once` writes all data to storage in a single operation.
     ///
     /// BlockWriter will call this API when:
     ///
-    /// - All the data has been written to the buffer and we can perform the upload at once.
+    /// - The buffer contains all data, so `BlockWriter` can upload it in one
+    ///   operation, for example, in a single network request.
     fn write_once(
         &self,
         size: u64,

data/core/core/src/raw/operation.rs

@@ -18,13 +18,13 @@
 use std::fmt::Display;
 use std::fmt::Formatter;
 
-/// Operation is the name of the operation that is being performed.
+/// Identifies the operation being performed.
 ///
-/// Most operations can be mapped to the methods of the `Access` trait,
-/// but we modify the names to make them more readable and clear for users.
+/// Most variants map to methods on the `Access` trait, although some names
+/// differ to improve readability.
 ///
-/// The same operation might have different meanings and costs in different
-/// storage services.
+/// An operation might have different meanings and costs depending on a
+/// storage service.
 #[derive(Debug, Copy, Clone, Hash, Eq, PartialEq, Default)]
 #[non_exhaustive]
 pub enum Operation {