docs: Polish core's quick start (#3896)

Signed-off-by: Xuanwo <[email protected]>

core/src/docs/mod.rs

@@ -29,12 +29,6 @@ pub mod internals;
 #[doc = include_str!("../../CHANGELOG.md")]
 pub mod changelog {}
 
-/// All features that provided by OpenDAL.
-///
-/// default feature: `rustls`, which enable rustls support.
-#[doc = include_str!("features.md")]
-pub mod features {}
-
 #[cfg(not(doctest))]
 pub mod rfcs;
 

core/src/lib.rs

@@ -20,19 +20,53 @@
 //! Apache OpenDAL™ is a data access layer that allows users to easily and
 //! efficiently retrieve data from various storage services in a unified way.
 //!
-//! - Documentation: All docs are carried by self, visit [`docs`] for more.
-//! - Services: All supported services could be found at [`services`].
-//! - Layers: All builtin layer could be found at [`layers`].
-//! - Features: All features could be found at [`features`][docs::features].
-//!
 //! # Quick Start
 //!
+//! OpenDAL's API entry points are [`Operator`] and [`BlockingOperator`]. 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::S3`] as an example:
+//!
 //! ```no_run
-//! use opendal::layers::LoggingLayer;
 //! use opendal::services;
 //! use opendal::Operator;
 //! use opendal::Result;
 //!
+//! fn main() -> Result<()> {
+//!     // Pick a builder and configure it.
+//!     let mut builder = services::S3::default();
+//!     builder.bucket("test");
+//!
+//!     // Init an operator
+//!     let op = Operator::new(builder)?.finish();
+//!     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::LoggingLayer`] as an example; this layer adds logging to
+//! every operation that OpenDAL performs.
+//!
+//! ```no_run
+//! use opendal::services;
+//! use opendal::Operator;
+//! use opendal::Result;
+//! use opendal::layers::LoggingLayer;
+//!
 //! #[tokio::main]
 //! async fn main() -> Result<()> {
 //!     // Pick a builder and configure it.
@@ -45,19 +79,46 @@
 //!         .layer(LoggingLayer::default())
 //!         .finish();
 //!
-//!     // Write data
-//!     op.write("hello.txt", "Hello, World!").await?;
+//!     Ok(())
+//! }
+//! ```
+//!
+//! ## Use operator
+//!
+//! The final step is to use the operator. OpenDAL supports both async [`Operator`]
+//! and blocking [`BlockingOperator`]. Please pick the one that fits your use case.
+//!
+//! Every Operator API follows the same pattern, take `read` as an example:
+//!
+//! - `read`: Execute a read operation.
+//! - `read_with`: Execute a read operation with additional options, like `range` and `if_match`.
+//! - `reader`: Create a reader for streaming data, enabling flexible access.
+//! - `reader_with`: Create a reader with advanced options.
+//!
+//! ```no_run
+//! use opendal::services;
+//! use opendal::Operator;
+//! use opendal::Result;
+//! use opendal::layers::LoggingLayer;
+//!
+//! #[tokio::main]
+//! async fn main() -> Result<()> {
+//!     // Pick a builder and configure it.
+//!     let mut builder = services::S3::default();
+//!     builder.bucket("test");
 //!
-//!     // Read data
-//!     let bs = op.read("hello.txt").await?;
+//!     // Init an operator
+//!     let op = Operator::new(builder)?
+//!         // Init with logging layer enabled.
+//!         .layer(LoggingLayer::default())
+//!         .finish();
 //!
-//!     // Fetch metadata
+//!     // Fetch this file's metadata
 //!     let meta = op.stat("hello.txt").await?;
-//!     let mode = meta.mode();
 //!     let length = meta.content_length();
 //!
-//!     // Delete
-//!     op.delete("hello.txt").await?;
+//!     // Read data from `hello.txt` with range `0..1024`.
+//!     let bs = op.read_with("hello.txt").range(0..1024).await?;
 //!
 //!     Ok(())
 //! }