From 88af193dca4a161f3888846c3d0071bdba72c2df Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Leon=20Gr=C3=BCnewald?= <leon@doggoat.de>
Date: Wed, 3 Jan 2024 15:19:29 +0100
Subject: [PATCH] Add documentation and prelude

---
 src/client.rs | 76 +++++++++++++++++++++++++++++++++++++--------------
 src/lib.rs    |  9 +++++-
 src/query.rs  |  0
 3 files changed, 63 insertions(+), 22 deletions(-)
 create mode 100644 src/query.rs

diff --git a/src/client.rs b/src/client.rs
index 19af285..9a07ba0 100644
--- a/src/client.rs
+++ b/src/client.rs
@@ -17,6 +17,23 @@ pub struct Client {
 }
 
 impl Client {
+
+    /// Create a new e621 client.
+    ///
+    /// ```
+    ///use r621::prelude::*;
+    ///use std::error::Error;
+    ///
+    ///#[tokio::main]
+    ///async fn main() -> Result<(), Box<dyn Error>> {
+    ///    let user_agent = "MyProject/1.0 (by username on e621)";
+    ///    let auth = Authentication::Authorized {
+    ///        username: "hexerade",
+    ///        apikey: "1nHrmzmsvJf26EhU1F7CjnjC"
+    ///    };
+    ///    let mut esix_client = Client::new(auth, user_agent);
+    ///}
+    /// ```
     pub fn new(auth: Authentication, useragent: &str) -> Result<Self> {
         let mut header_map = HeaderMap::new();
         header_map.append(USER_AGENT, HeaderValue::from_str(useragent)?);
@@ -37,6 +54,44 @@ impl Client {
         })
     }
 
+    /// Query the e621 api for posts
+    ///
+    /// ```
+    ///use r621::prelude::*;
+    ///use std::error::Error;
+    ///
+    ///#[tokio::main]
+    ///async fn main() -> Result<(), Box<dyn Error>> {
+    ///    let user_agent = "MyProject/1.0 (by username on e621)";
+    ///    let auth = Authentication::Authorized {
+    ///        username: "hexerade",
+    ///        apikey: "1nHrmzmsvJf26EhU1F7CjnjC"
+    ///    };
+    ///    let mut esix_client = Client::new(auth, user_agent);
+    ///    let posts = esix_client.list_posts(None, Some("lucario"), None).await?;
+    ///}
+    /// ```
+    pub async fn list_posts(
+        &mut self,
+        limit: Option<u16>,
+        tags: Option<String>,
+        page: Option<u32>,
+    ) -> Result<Vec<Post>> {
+        self.request_limiter().await;
+        let res = self.list_posts_raw(limit, tags, page).await?;
+        let text = res.text().await?;
+
+        if cfg!(debug) {
+            let mut debug_file = std::fs::OpenOptions::new()
+                .write(true)
+                .create(true)
+                .open("/tmp/debug.json")?;
+            debug_file.write_all(text.as_bytes())?;
+        }
+
+        Ok(serde_json::from_str::<Posts>(text.as_str())?.into())
+    }
+
     async fn request_limiter(&mut self) {
         let wait_time = Instant::now() - self.last_request_time;
         if Instant::now() - self.last_request_time > Duration::from_secs(1) {
@@ -86,27 +141,6 @@ impl Client {
         self.request_counter = self.request_counter+1;
         Ok(self.http_client.get(url.as_str()).send().await?)
     }
-
-    pub async fn list_posts(
-        &mut self,
-        limit: Option<u16>,
-        tags: Option<String>,
-        page: Option<u32>,
-    ) -> Result<Vec<Post>> {
-        self.request_limiter().await;
-        let res = self.list_posts_raw(limit, tags, page).await?;
-        let text = res.text().await?;
-
-        if cfg!(debug) {
-            let mut debug_file = std::fs::OpenOptions::new()
-                .write(true)
-                .create(true)
-                .open("/tmp/debug.json")?;
-            debug_file.write_all(text.as_bytes())?;
-        }
-
-        Ok(serde_json::from_str::<Posts>(text.as_str())?.into())
-    }
 }
 
 #[derive(Clone, Copy, Debug)]
diff --git a/src/lib.rs b/src/lib.rs
index 4863ac4..123e78d 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -1,3 +1,10 @@
 pub mod client;
-mod errors;
+pub mod errors;
 pub mod post;
+pub mod query;
+
+pub mod prelude {
+    pub use crate::client::Client;
+    pub use crate::client::Authentication;
+    pub use crate::post::Post;
+}
diff --git a/src/query.rs b/src/query.rs
new file mode 100644
index 0000000..e69de29