refactor(lib)!: adjust layout of library exports and improve document…

…ation

cli/src/cli/convert.rs

@@ -9,7 +9,7 @@ use comfy_table::{
 };
 use lib_frankfurter::{
     api::{self, ServerClient},
-    data::{Currency, CurrencyValue},
+    Currency, CurrencyValue,
 };
 use termcolor::StandardStream;
 

cli/src/cli/period.rs

@@ -8,7 +8,7 @@ use comfy_table::{
 };
 use lib_frankfurter::{
     api::{self, ServerClient},
-    data::{Currency, CurrencyValue},
+    Currency, CurrencyValue,
 };
 use termcolor::StandardStream;
 

lib/examples/basic.rs

@@ -1,19 +1,16 @@
-extern crate reqwest;
-extern crate serde_json;
-extern crate tokio;
-extern crate url;
-
-use chrono::NaiveDate;
-use lib_frankfurter::api::{convert, currencies, period, ServerClient};
-use url::Url;
+use lib_frankfurter::{
+    api::{convert, currencies, period, ServerClient},
+    chrono::NaiveDate,
+    url::Url,
+};
 
 #[tokio::main]
 async fn main() {
     let server_client: ServerClient = Url::parse("http://localhost:8080")
         .map(ServerClient::new)
         .unwrap_or_default();
 
-    // Fetch currencies - this request does not accept any additional options
+    // Fetch supported currencies - this request does not accept any additional options
     match server_client
         .currencies(currencies::Request::default())
         .await

lib/src/api/convert.rs

@@ -1,3 +1,5 @@
+//! [`Request`] and [`Response`] types for requesting exchange rates for a specific date (latest by default).
+
 use std::borrow::Cow;
 
 use chrono::NaiveDate;

lib/src/api/currencies.rs

@@ -1,3 +1,6 @@
+//! [`Request`] and [`Response`] types for requesting the latest supported currency codes and their
+//! names.
+
 use std::{borrow::Cow, collections::BTreeMap};
 
 use serde::{Deserialize, Serialize};

lib/src/api/mod.rs

@@ -1,7 +1,4 @@
-//! Bindings to the Frankfurter API
-//!
-//! The current bindings were generated using the
-//! [HTTP API documentation](https://frankfurter.dev/).
+//! Interface to the Frankfurter API.
 
 pub mod convert;
 pub mod currencies;
@@ -112,21 +109,23 @@ impl ServerClient {
         self.get::<convert::Response>(req).await
     }
 
-    /// Request a time series of historical exchange rates.
+    /// Request historical exchange rates for a given time period.
     pub async fn period(&self, req: period::Request) -> Result<period::Response> {
         self.get::<period::Response>(req).await
     }
 
-    /// Request the supported currency codes and their full names.
+    /// Request the latest supported currency codes and their full names.
     pub async fn currencies(&self, req: currencies::Request) -> Result<currencies::Response> {
         self.get::<currencies::Response>(req).await
     }
 }
 
+/// An endpoint's URL.
 pub type EndpointUrl = Cow<'static, str>;
+/// Query parameters to be passed to an endpoint.
 pub type QueryParams = Vec<(&'static str, String)>;
 
-/// Utility trait to provide a common interface for server client requests.
+/// Utility trait to provide a common interface for requests.
 pub trait ServerClientRequest {
     fn get_url(&self) -> EndpointUrl;
     fn ensure_valid(&self) -> Result<()>;

lib/src/api/period.rs

@@ -1,3 +1,6 @@
+//! [`Request`] and [`Response`] types for requesting historical exchange rates for a
+//! given time period.
+
 use std::{borrow::Cow, collections::BTreeMap};
 
 use chrono::{NaiveDate, Utc};

lib/src/data.rs

@@ -75,7 +75,7 @@ impl Default for Currency {
     }
 }
 
-/// Value of a currency.
+/// Value of a currency. Simple wrapper around an [`f64`].
 ///
 /// This is a wrapper around [`f64`] to ensure that values are rounded to 2 decimal places.
 #[derive(Clone, Copy, PartialEq, PartialOrd, Debug, Deserialize, Serialize)]

lib/src/error.rs

@@ -3,8 +3,10 @@ use reqwest::StatusCode;
 
 use crate::data::Currency;
 
-pub type Result<T> = std::result::Result<T, Error>;
+/// [`std::result::Result`] wrapper for convenience.
+pub(super) type Result<T> = std::result::Result<T, Error>;
 
+/// Possible errors that can be encountered when making requests using the [`crate::api::ServerClient`].
 #[derive(Debug, thiserror::Error)]
 pub enum Error {
     #[error("The target currencies '{}' include the base currency '{base}'", .targets.iter().map(|t| t.to_string()).collect::<Vec<String>>().join(","))]

lib/src/lib.rs

@@ -1,3 +1,20 @@
+// #![doc = include_str!("../../README.md")]
+//! Rust bindings to the [Frankfurter API](https://github.com/lineofflight/frankfurter)
+//!
+//! ## Usage
+//!
+//! ```rust
+#![doc = include_str!("../examples/basic.rs")]
+//! ```
+
 pub mod api;
-pub mod data;
-pub mod error;
+mod data;
+mod error;
+
+// RE-EXPORTS
+pub use chrono;
+pub use data::*;
+pub use error::*;
+pub use reqwest;
+pub use serde_json;
+pub use url;

lib/tests/endpoint_convert.rs

@@ -1,9 +1,6 @@
 mod shared;
 use chrono::NaiveDate;
-use lib_frankfurter::{
-    api::convert,
-    data::{Currency, CurrencyValue},
-};
+use lib_frankfurter::{api::convert, Currency, CurrencyValue};
 use pretty_assertions::assert_eq;
 use shared::{get_invalid_server, get_server};
 

lib/tests/endpoint_period.rs

@@ -1,9 +1,6 @@
 mod shared;
 use chrono::{Datelike, NaiveDate};
-use lib_frankfurter::{
-    api::period,
-    data::{Currency, CurrencyValue},
-};
+use lib_frankfurter::{api::period, Currency, CurrencyValue};
 use pretty_assertions::assert_eq;
 use shared::{get_invalid_server, get_server};