From 2e9bce94381a4a6d3b336fac7f01050480a6b5c9 Mon Sep 17 00:00:00 2001 From: Noel Date: Sun, 12 Jan 2025 18:10:36 -0800 Subject: [PATCH] Improve documentation once more --- crates/azure/README.md | 2 +- crates/azure/src/config.rs | 2 +- crates/azure/src/lib.rs | 77 +++++++++++++++++++++++++++++++++++++- crates/fs/src/config.rs | 2 +- crates/fs/src/lib.rs | 65 +++++++++++++++++++++++++++++++- crates/fs/src/service.rs | 2 +- 6 files changed, 144 insertions(+), 6 deletions(-) diff --git a/crates/azure/README.md b/crates/azure/README.md index cb08162..22d7bd6 100644 --- a/crates/azure/README.md +++ b/crates/azure/README.md @@ -6,7 +6,7 @@ | Crate Features | Description | Enabled by default? | | :------------- | :----------------------------------------------------------------------------------- | ------------------- | -| `export-azure` | Exports all the used Azure crates as a module called `core` | Yes. | +| `export-azure` | Exports all the used Azure crates as a module called `core` | No. | | `unstable` | Tap into unstable features from `remi_azure` and the `remi` crate. | No. | | [`tracing`] | Enables the use of [`tracing::instrument`] and emit events for actions by the crate. | No. | | [`serde`] | Enables the use of **serde** in `StorageConfig` | No. | diff --git a/crates/azure/src/config.rs b/crates/azure/src/config.rs index bf9761b..e59d263 100644 --- a/crates/azure/src/config.rs +++ b/crates/azure/src/config.rs @@ -98,7 +98,7 @@ impl TryFrom for ContainerClient { } } -/// Newtype enumeration around [`azure_core::CloudLocation`]. +/// Newtype enumeration around [`azure_storage::CloudLocation`]. #[derive(Debug, Clone, PartialEq)] #[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))] #[cfg_attr(feature = "serde", serde(rename_all = "lowercase"))] diff --git a/crates/azure/src/lib.rs b/crates/azure/src/lib.rs index c8a417a..a426ecd 100644 --- a/crates/azure/src/lib.rs +++ b/crates/azure/src/lib.rs @@ -19,24 +19,99 @@ // OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE // SOFTWARE. +//! # ๐Ÿปโ€โ„๏ธ๐Ÿงถ `remi_azure` +//! This crate is an official implementation of [`remi::StorageService`] for Microsoft's +//! Azure Blob Storage service using the unofficial Azure crates: [`azure_core`], [`azure_storage`], +//! and [`azure_storage_blobs`]. +//! +//! [`remi::StorageService`]: https://docs.rs/remi/*/remi/trait.StorageService.html +//! [`azure_storage_blobs`]: https://docs.rs/azure-storage-blobs +//! [`azure_storage`]: https://docs.rs/azure-storage +//! [`azure_core`]: https://docs.rs/azure-core +//! +//! ## Example +//! ```rust,no_run +//! // Cargo.toml: +//! // +//! // [dependencies] +//! // remi = "^0" +//! // remi-azure = "^0" +//! // tokio = { version = "^1", features = ["full"] } +//! +//! use remi_azure::{StorageService, StorageConfig, Credential, CloudLocation}; +//! use remi::{StorageService as _, UploadRequest}; +//! +//! #[tokio::main] +//! async fn main() { +//! let storage = StorageService::new(StorageConfig { +//! credentials: Credential::Anonymous, +//! container: "my-container".into(), +//! location: CloudLocation::Public("my-account".into()), +//! }).unwrap(); +//! +//! // Initialize the container. This will: +//! // +//! // * create `my-container` if it doesn't exist +//! storage.init().await.unwrap(); +//! +//! // Now we can upload files to Azure. +//! +//! // We define a `UploadRequest`, which will set the content type to `text/plain` and set the +//! // contents of `weow.txt` to `weow fluff`. +//! let upload = UploadRequest::default() +//! .with_content_type(Some("text/plain")) +//! .with_data("weow fluff"); +//! +//! // Let's upload it! +//! storage.upload("weow.txt", upload).await.unwrap(); +//! +//! // Let's check if it exists! This `assert!` will panic if it failed +//! // to upload. +//! assert!(storage.exists("weow.txt").await.unwrap()); +//! } +//! ``` +//! +//! ## Crate Features +//! | Crate Features | Description | Enabled by default? | +//! | :------------- | :----------------------------------------------------------------------------------- | ------------------- | +//! | `export-azure` | Exports all the used Azure crates as a module called `core` | No. | +//! | `unstable` | Tap into unstable features from `remi_azure` and the `remi` crate. | No. | +//! | [`tracing`] | Enables the use of [`tracing::instrument`] and emit events for actions by the crate. | No. | +//! | [`serde`] | Enables the use of **serde** in `StorageConfig` | No. | +//! | [`log`] | Emits log records for actions by the crate | No. | +//! +//! [`tracing::instrument`]: https://docs.rs/tracing/*/tracing/attr.instrument.html +//! [`tracing`]: https://crates.io/crates/tracing +//! [`serde`]: https://serde.rs +//! [`log`]: https://crates.io/crates/log + #![doc(html_logo_url = "https://cdn.floofy.dev/images/trans.png")] +#![doc(html_favicon_url = "https://cdn.floofy.dev/images/trans.png")] #![cfg_attr(any(noeldoc, docsrs), feature(doc_cfg))] -#![doc = include_str!("../README.md")] #[cfg(feature = "export-azure")] #[cfg_attr(any(noeldoc, docsrs), doc(cfg(feature = "export-azure")))] /// Exports the [`azure_core`], [`azure_storage`], and [`azure_storage_blobs`] /// crates without defining them as owned dependencies. +/// +/// [`azure_storage_blobs`]: https://docs.rs/azure-storage-blobs +/// [`azure_storage`]: https://docs.rs/azure-storage +/// [`azure_core`]: https://docs.rs/azure-core pub mod core { pub use azure_core::*; /// Exports the [`azure_storage`] and [`azure_storage_blobs`] /// crates without defining them as owned dependencies. + /// + /// [`azure_storage_blobs`]: https://docs.rs/azure-storage-blobs + /// [`azure_storage`]: https://docs.rs/azure-storage #[cfg_attr(any(noeldoc, docsrs), doc(cfg(feature = "export-azure")))] pub mod storage { pub use azure_storage::*; /// Exports the [`azure_storage_blobs`] crate without defining them as owned dependencies. + /// + /// [`azure_storage_blobs`]: https://docs.rs/azure-storage-blobs pub use azure_storage_blobs as blobs; } } diff --git a/crates/fs/src/config.rs b/crates/fs/src/config.rs index fc9d6c4..3a4e6dc 100644 --- a/crates/fs/src/config.rs +++ b/crates/fs/src/config.rs @@ -30,7 +30,7 @@ pub struct StorageConfig { } impl StorageConfig { - /// Creates a new [`Config`] instance. + /// Creates a new [`StorageConfig`] with a given root directory. pub fn new>(path: P) -> StorageConfig { StorageConfig { directory: path.as_ref().into(), diff --git a/crates/fs/src/lib.rs b/crates/fs/src/lib.rs index d864f17..bdc6dae 100644 --- a/crates/fs/src/lib.rs +++ b/crates/fs/src/lib.rs @@ -19,9 +19,72 @@ // OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE // SOFTWARE. +//! # ๐Ÿปโ€โ„๏ธ๐Ÿงถ `remi_fs` +//! This crate is an official implementation of [`remi::StorageService`] that uses +//! the local filesystem for operations. +//! +//! [`remi::StorageService`]: https://docs.rs/remi/*/remi/trait.StorageService.html +//! +//! ## Example +//! ```rust,no_run +//! // Cargo.toml: +//! // +//! // [dependencies] +//! // remi = "^0" +//! // remi-fs = "^0" +//! // tokio = { version = "^1", features = ["full"] } +//! +//! use remi_fs::{StorageService, StorageConfig}; +//! use remi::{StorageService as _, UploadRequest}; +//! +//! #[tokio::main] +//! async fn main() { +//! // Initialize a `StorageService` that uses your local filesystem for storing files. +//! let storage = StorageService::new("./data"); +//! +//! // Next, we will run the `init` function which will create +//! // the ./data directory if it doesn't exist already. +//! storage.init().await.unwrap(); +//! +//! // We define a `UploadRequest`, which will set the content type to `text/plain` and set the +//! // contents of `weow.txt` to `weow fluff`. +//! let upload = UploadRequest::default() +//! .with_content_type(Some("text/plain")) +//! .with_data("weow fluff"); +//! +//! // Let's upload it! +//! storage.upload("./weow.txt", upload).await.unwrap(); +//! +//! // Let's check if it exists! This `assert!` will panic if it failed +//! // to upload. +//! assert!(storage.exists("./weow.txt").await.unwrap()); +//! } +//! ``` +//! +//! ## Crate Features +//! | Crate Features | Description | Enabled by default? | +//! | :---------------- | :------------------------------------------------------------------------------------- | -------------------- | +//! | `unstable` | Tap into unstable features from `remi_fs` and the `remi` crate. | No. | +//! | [`serde_yaml_ng`] | Allows to detect YAML documents with the [`serde_yaml_ng`] crate. | No. | +//! | [`serde_json`] | Uses the [`serde_json`] crate to detect JSON documents and return `application/json` | No. | +//! | [`file-format`] | Uses the [`file-format`] crate to find media types on any external datatype. | Yes. | +//! | [`tracing`] | Enables the use of [`tracing::instrument`] and emit events for actions by the crate. | No. | +//! | [`infer`] | Uses the [`infer`] crate to infer external datatypes and map them to their media type. | Yes. | +//! | [`serde`] | Enables the use of **serde** in `StorageConfig` | No. | +//! | [`log`] | Emits log records for actions by the crate | No. | +//! +//! [`tracing::instrument`]: https://docs.rs/tracing/*/tracing/attr.instrument.html +//! [`serde_yaml_ng`]: https://crates.io/crates/serde_yaml_ng +//! [`file-format`]: https://crates.io/crates/file-format +//! [`serde_json`]: https://crates.io/crates/serde_json +//! [`tracing`]: https://crates.io/crates/tracing +//! [`infer`]: https://crates.io/crates/infer +//! [`serde`]: https://serde.rs +//! [`log`]: https://crates.io/crates/log + #![doc(html_logo_url = "https://cdn.floofy.dev/images/trans.png")] +#![doc(html_favicon_url = "https://cdn.floofy.dev/images/trans.png")] #![cfg_attr(any(noeldoc, docsrs), feature(doc_cfg))] -#![doc = include_str!("../README.md")] mod config; mod content_type; diff --git a/crates/fs/src/service.rs b/crates/fs/src/service.rs index 266993d..4b8969d 100644 --- a/crates/fs/src/service.rs +++ b/crates/fs/src/service.rs @@ -64,7 +64,7 @@ impl StorageService { /// Attempts to normalize a given path and returns a canonical, absolute /// path. It must follow some strict rules: /// - /// * If the path starts with `./`, then it will resolve from [`Config::directory`] if + /// * If the path starts with `./`, then it will resolve from [`StorageConfig::directory`] if /// the directory was found. Otherwise, it'll use the current directory. /// /// * If the path starts with `~/`, then it will resolve from the home directory from [`etcetera::home_dir`].