Add crate docs

Author: cameronfyfe

src/client.rs

@@ -2,12 +2,25 @@ use super::{Api, Result};
 use reqwest::RequestBuilder;
 use serde_json::Value;
 
+/// Client for accessing Listen Notes API.
 pub struct Client<'a> {
+    /// HTTP client.
     client: reqwest::Client,
+    /// API context.
     api: Api<'a>,
 }
 
 impl Client<'_> {
+    /// Creates new Listen API Client.
+    ///
+    /// To access production API:
+    /// ```
+    /// let client = podcast_api::Client::new(reqwest::Client::new(), Some("YOUR-API-KEY"));
+    /// ```
+    /// To access mock API:
+    /// ```
+    /// let client = podcast_api::Client::new(reqwest::Client::new(), None);
+    /// ```
     pub fn new<'a>(client: reqwest::Client, id: Option<&'a str>) -> Client<'a> {
         Client {
             client,
@@ -19,30 +32,41 @@ impl Client<'_> {
         }
     }
 
+    /// Calls [`GET /search`](https://www.listennotes.com/api/docs/#get-api-v2-search) with supplied parameters.
     pub async fn search(&self, parameters: &Value) -> Result<Value> {
         self.get("search", parameters).await
     }
 
+    /// Calls [`GET /typeahead`](https://www.listennotes.com/api/docs/#get-api-v2-typeahead) with supplied parameters.
     pub async fn typeahead(&self, parameters: &Value) -> Result<Value> {
         self.get("typeahead", parameters).await
     }
 
+    /// Calls [`GET /best_podcasts`](https://www.listennotes.com/api/docs/#get-api-v2-best_podcasts) with supplied parameters.
     pub async fn best_podcasts(&self, parameters: &Value) -> Result<Value> {
         self.get("best_podcasts", parameters).await
     }
 
+    /// Calls [`GET /podcasts/{id}`](https://www.listennotes.com/api/docs/#get-api-v2-podcasts-id) with supplied parameters.
     pub async fn podcast(&self, id: &str, parameters: &Value) -> Result<Value> {
         self.get(&format!("podcasts/{}", id), parameters).await
     }
 
+    /// Calls [`POST /podcasts`](https://www.listennotes.com/api/docs/#post-api-v2-podcasts) with supplied parameters.
     pub async fn podcasts(&self, parameters: &Value) -> Result<Value> {
         self.post("podcasts", parameters).await
     }
 
+    /// Calls [`GET /episodes/{id}`](https://www.listennotes.com/api/docs/#get-api-v2-episodes-id) with supplied parameters.
     pub async fn episode(&self, id: &str, parameters: &Value) -> Result<Value> {
         self.get(&format!("episodes/{}", id), parameters).await
+    }
+
+    /// Calls [`POST /episodes`](https://www.listennotes.com/api/docs/#post-api-v2-episodes) with supplied parameters.
     pub async fn episodes(&self, parameters: &Value) -> Result<Value> {
         self.post("episodes", parameters).await
+    }
+
     async fn get(&self, endpoint: &str, parameters: &Value) -> Result<Value> {
         let request = self
             .client
@@ -74,15 +98,3 @@ impl Client<'_> {
         .await?)
     }
 }
-
-trait AddField {
-    fn with(&self, key: &str, value: &str) -> Self;
-}
-
-impl AddField for Value {
-    fn with(&self, key: &str, value: &str) -> Self {
-        let mut p = self.clone();
-        p[key] = json!(value);
-        p
-    }
-}

src/error.rs

@@ -1,6 +1,9 @@
+/// Error for API calls from [`Client`](super::Client).
 #[derive(Debug)]
 pub enum Error {
+    /// Error from http client.
     Reqwest(reqwest::Error),
+    /// Error from JSON creation/processing.
     Json(serde_json::Error),
 }
 

src/lib.rs

@@ -1,3 +1,40 @@
+//! Official library for accessing the [Listen API](https://www.listennotes.com/api) by [Listen Notes](https://www.listennotes.com).
+//! 
+//! # Quick Start Example
+//!
+//! ```
+//! use serde_json::json;
+//!
+//! #[tokio::main]
+//! async fn main() {
+//!     // Api Key  (None => Test API, Some(key) => Production API)
+//!     let api_key = None;
+//!
+//!     // Create client
+//!     let client = podcast_api::Client::new(reqwest::Client::new(), api_key);
+//!
+//!     // Call API
+//!     match client
+//!         .typeahead(&json!({
+//!             "q": "startup",
+//!             "show_podcasts": 1
+//!         }))
+//!         .await
+//!     {
+//!         Ok(response) => {
+//!             println!("Successfully called \"typeahead\" endpoint.");
+//!             println!("Response Body:");
+//!             println!("{:?}", response);
+//!         }
+//!         Err(err) => {
+//!             println!("Error calling \"typeahead\" endpoint:");
+//!             println!("{:?},", err);
+//!         }
+//!     };
+//! }
+//! ```
+#![deny(missing_docs)]
+
 mod api;
 mod client;
 mod error;
@@ -6,4 +43,5 @@ use api::Api;
 
 pub use client::Client;
 pub use error::Error;
+/// Result for API calls from [`Client`]
 pub type Result<T> = std::result::Result<T, error::Error>;