From a30044278c0610bbc43de236c888e8c4cf04c9ab Mon Sep 17 00:00:00 2001
From: asonix <asonix@asonix.dog>
Date: Fri, 24 Nov 2023 11:38:14 -0600
Subject: [PATCH] Improve documentation for using pict-rs as a library

---
 Cargo.toml                |  3 +++
 src/config.rs             |  2 ++
 src/config/commandline.rs |  2 +-
 src/lib.rs                | 52 ++++++++++++++++++++++++++++++++++++---
 4 files changed, 54 insertions(+), 5 deletions(-)

diff --git a/Cargo.toml b/Cargo.toml
index e87bbe0..b3f714a 100644
--- a/Cargo.toml
+++ b/Cargo.toml
@@ -86,3 +86,6 @@ uuid = { version = "1", features = ["serde", "std", "v4", "v7"] }
 version = "0.7.8"
 default-features = false
 features = ["emit_event_on_error", "opentelemetry_0_21"]
+
+[dev-dependencies]
+tokio-uring = { version = "0.4", features = ["bytes"] }
diff --git a/src/config.rs b/src/config.rs
index 25cf0e7..13e9104 100644
--- a/src/config.rs
+++ b/src/config.rs
@@ -54,6 +54,8 @@ impl ConfigSource<PathBuf, ()> {
     }
 }
 
+// deserialized Configuration for the pict-rs application
+#[derive(Debug)]
 pub struct PictRsConfiguration {
     pub(crate) config: Configuration,
     pub(crate) operation: Operation,
diff --git a/src/config/commandline.rs b/src/config/commandline.rs
index fa9258e..7c1e264 100644
--- a/src/config/commandline.rs
+++ b/src/config/commandline.rs
@@ -470,7 +470,7 @@ pub(super) struct Output {
 }
 
 #[allow(clippy::large_enum_variant)]
-#[derive(Clone)]
+#[derive(Clone, Debug)]
 pub(crate) enum Operation {
     Run,
     MigrateStore {
diff --git a/src/lib.rs b/src/lib.rs
index 1d7dc32..1f9f854 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -1961,13 +1961,10 @@ impl<P: AsRef<Path>, T: serde::Serialize> ConfigSource<P, T> {
     ///
     /// ```rust
     /// fn main() -> Result<(), Box<dyn std::error::Error>> {
-    ///     pict_rs::ConfigSource::memory(serde_json::json!({
+    ///     let configuration = pict_rs::ConfigSource::memory(serde_json::json!({
     ///         "server": {
     ///             "address": "127.0.0.1:8080"
     ///         },
-    ///         "old_db": {
-    ///             "path": "./old"
-    ///         },
     ///         "repo": {
     ///             "type": "sled",
     ///             "path": "./sled-repo"
@@ -2036,6 +2033,29 @@ impl PictRsConfiguration {
     /// Run the pict-rs application on a tokio `LocalSet`
     ///
     /// This must be called from within `tokio::main` directly
+    ///
+    /// Example:
+    /// ```rust
+    /// #[tokio::main]
+    /// async fn main() -> color_eyre::Result<()> {
+    ///     let pict_rs_server = pict_rs::ConfigSource::memory(serde_json::json!({
+    ///         "repo": {
+    ///             "type": "sled",
+    ///             "path": "/tmp/pict-rs/run-on-localset/sled-repo",
+    ///         },
+    ///         "store": {
+    ///             "type": "filesystem",
+    ///             "path": "/tmp/pict-rs/run-on-localset/files",
+    ///         },
+    ///     }))
+    ///         .init::<&str>(None)?
+    ///         .run_on_localset();
+    ///
+    ///     let _ = tokio::time::timeout(std::time::Duration::from_secs(1), pict_rs_server).await;
+    ///
+    ///     Ok(())
+    /// }
+    /// ```
     pub async fn run_on_localset(self) -> color_eyre::Result<()> {
         tokio::task::LocalSet::new().run_until(self.run()).await
     }
@@ -2044,6 +2064,30 @@ impl PictRsConfiguration {
     ///
     /// This must be called from within a tokio `LocalSet`, which is created by default for
     /// actix-rt runtimes, and by tokio_uring
+    ///
+    /// Example:
+    /// ```rust
+    /// fn main() -> color_eyre::Result<()> {
+    ///     tokio_uring::start(async move {
+    ///         let pict_rs_server = pict_rs::ConfigSource::memory(serde_json::json!({
+    ///             "repo": {
+    ///                 "type": "sled",
+    ///                 "path": "/tmp/pict-rs/run/sled-repo",
+    ///             },
+    ///             "store": {
+    ///                 "type": "filesystem",
+    ///                 "path": "/tmp/pict-rs/run/files",
+    ///             },
+    ///         }))
+    ///         .init::<&str>(None)?
+    ///         .run();
+    ///
+    ///         let _ = tokio::time::timeout(std::time::Duration::from_secs(1), pict_rs_server).await;
+    ///
+    ///         Ok(())
+    ///     })
+    /// }
+    /// ```
     pub async fn run(self) -> color_eyre::Result<()> {
         let PictRsConfiguration { config, operation } = self;