Improve documentation once more

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.                 |

crates/azure/src/config.rs

@@ -98,7 +98,7 @@ impl TryFrom<StorageConfig> 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"))]

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;
     }
 }

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<P: AsRef<Path>>(path: P) -> StorageConfig {
         StorageConfig {
             directory: path.as_ref().into(),

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;

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`].