bump fusio to 0.3.0 & basic docs

fusio-dispatch/Cargo.toml

@@ -4,7 +4,7 @@ edition.workspace = true
 license.workspace = true
 name = "fusio-dispatch"
 repository.workspace = true
-version = "0.2.0"
+version = "0.2.1"
 
 [features]
 aws = ["fusio/aws"]
@@ -14,6 +14,6 @@ object_store = ["dep:fusio-object-store", "object_store/aws"]
 tokio = ["fusio/tokio"]
 
 [dependencies]
-fusio = { version = "0.2.1", path = "../fusio" }
+fusio = { version = "0.3.0", path = "../fusio" }
 fusio-object-store = { version = "0.2.0", path = "../fusio-object-store", optional = true }
 object_store = { version = "0.11", optional = true }

fusio-object-store/Cargo.toml

@@ -4,11 +4,11 @@ edition.workspace = true
 license.workspace = true
 name = "fusio-object-store"
 repository.workspace = true
-version = "0.2.0"
+version = "0.2.1"
 
 [dependencies]
 async-stream = { version = "0.3" }
-fusio = { version = "0.2.1", path = "../fusio", features = [
+fusio = { version = "0.3.0", path = "../fusio", features = [
     "bytes",
     "dyn",
     "object_store",

fusio-parquet/Cargo.toml

@@ -4,11 +4,11 @@ edition.workspace = true
 license.workspace = true
 name = "fusio-parquet"
 repository.workspace = true
-version = "0.2.0"
+version = "0.2.1"
 
 [dependencies]
 bytes = { workspace = true }
-fusio = { version = "0.2.1", path = "../fusio", features = [
+fusio = { version = "0.3.0", path = "../fusio", features = [
     "bytes",
     "dyn",
     "tokio",

fusio/Cargo.toml

@@ -3,8 +3,9 @@ description = "Fusio provides lean, minimal cost abstraction and extensible Read
 edition.workspace = true
 license.workspace = true
 name = "fusio"
+readme = "../README.md"
 repository.workspace = true
-version = "0.2.1"
+version = "0.3.0"
 
 [features]
 aws = [

fusio/src/lib.rs

@@ -17,37 +17,73 @@ pub use dynamic::{DynRead, DynWrite};
 pub use error::Error;
 pub use impls::*;
 
-/// # Safety
-/// Do not implement it directly
 #[cfg(not(feature = "no-send"))]
-pub unsafe trait MaybeSend: Send {}
+pub unsafe trait MaybeSend: Send {
+    //! Considering lots of runtimes does not require `Send` for [`std::future::Future`] and
+    //! [`futures::stream::Stream`], we provide a trait to represent the future or stream that
+    //! may not require `Send`. Users could switch the feature `no-send` at compile-time to
+    //! disable the `Send` bound for [`std::future::Future`] and [`futures::stream::Stream`].
+    //!
+    //! # Safety
+    //! Do not implement it directly.
+}
 
 /// # Safety
 /// Do not implement it directly
 #[cfg(feature = "no-send")]
-pub unsafe trait MaybeSend {}
+pub unsafe trait MaybeSend {
+    //! Considering lots of runtimes does not require [`Send`] for [`std::future::Future`] and
+    //! [`futures::stream::Stream`], we provide a trait to represent the future or stream that
+    //! may not require `Send`. Users could switch the feature `no-send` at compile-time to
+    //! disable the `Send` bound for [`std::future::Future`] and [`futures::stream::Stream`].
+    //!
+    //! # Safety
+    //! Do not implement it directly
+}
 
 #[cfg(not(feature = "no-send"))]
 unsafe impl<T: Send> MaybeSend for T {}
 #[cfg(feature = "no-send")]
 unsafe impl<T> MaybeSend for T {}
 
-/// # Safety
-/// Do not implement it directly
 #[cfg(not(feature = "no-send"))]
-pub unsafe trait MaybeSync: Sync {}
+pub unsafe trait MaybeSync: Sync {
+    //! Same as [`MaybeSend`], but for [`Sync`].
+    //!
+    //! # Safety
+    //! Do not implement it directly
+}
 
-/// # Safety
-/// Do not implement it directly
 #[cfg(feature = "no-send")]
-pub unsafe trait MaybeSync {}
+pub unsafe trait MaybeSync {
+    //! Same as [`MaybeSend`], but for [`Sync`].
+    //!
+    //! # Safety
+    //! Do not implement it directly
+}
 
 #[cfg(not(feature = "no-send"))]
 unsafe impl<T: Sync> MaybeSync for T {}
 #[cfg(feature = "no-send")]
 unsafe impl<T> MaybeSync for T {}
 
 pub trait Write: MaybeSend {
+    //! The core trait for writing data,
+    //! it is similar to [`std::io::Write`], but it takes the ownership of the buffer,
+    //! because completion-based IO requires the buffer to be pinned and should be safe to
+    //! cancellation.
+    //!
+    //! [`Write`] represents "truncate to 0 then append all" semantics,
+    //! which means the file will be truncated to 0 at first,
+    //! and each write operation will be appended to the end of the file.
+    //!
+    //! Contents are not be garanteed to be written to the file until the [`Write::close`] method is
+    //! called, [`Write::flush`] may be used to flush the data to the file in some
+    //! implementations, but not all implementations will do so.
+    //!
+    //! Whether the operation is successful or not, the buffer will be returned,
+    //! [`fusio`] promises that the returned buffer will be the same as the input buffer.
+
     fn write_all<B: IoBuf>(
         &mut self,
         buf: B,
@@ -59,6 +95,20 @@ pub trait Write: MaybeSend {
 }
 
 pub trait Read: MaybeSend + MaybeSync {
+    //! The core trait for reading data,
+    //! it is similar to [`std::io::Read`],
+    //! but it takes the ownership of the buffer,
+    //! because completion-based IO requires the buffer to be pinned and should be safe to
+    //! cancellation.
+    //!
+    //! [`Read`] represents "read exactly at" semantics,
+    //! which means the read operation will start at the specified position.
+    //!
+    //! The buffer will be returned with the result, whether the operation is successful or not,
+    //! [`fusio`] promises that the returned buffer will be the same as the input buffer.
+    //!
+    //! If you want sequential reading, try [`SeqRead`].
+
     fn read_exact_at<B: IoBufMut>(
         &mut self,
         buf: B,