Add all missing docs

src/api.rs

@@ -1,3 +1,47 @@
+#![warn(missing_docs)]
+
+//! API endpoint structures.
+//!
+//! The types in this module are meant to aid in constructing the appropriate calls using type-safe
+//! Rust idioms.
+//!
+//! All endpoints use the builder pattern and have their members as private so that there are no
+//! API implications of adding new members for additional query parameters in future GitLab
+//! releases.
+//!
+//! # Example
+//!
+//! ```rust,no_run
+//! use serde::Deserialize;
+//! use marketstack::Marketstack;
+//! use marketstack::api::{self, Eod, Query};
+//!
+//! // The return type of an `EodData`. Note that Marketstack may contain more information, but you can
+//! // define your structure to only fetch what is needed.
+//! #[derive(Serialize, Deserialize, Debug, Clone)]
+//! pub struct EodData {
+//!     pub pagination: PaginationInfo,
+//!     pub data: Vec<EodDataItem>,
+//! }
+//!
+//! // Create the client.
+//! let client = Marketstack::new("api.marketstack.com", "private-token").unwrap();
+//!
+//! // OR create an insecure token (if on the Free plan).
+//! let client = Marketstack::new_insecure("api.marketstack.com", "private-token").unwrap();
+//!
+//! // Create a simple endpoint. This one gets the "eod" for the AAPL symbol.
+//! let endpoint = eod::Eod::builder().symbol("AAPL").build().unwrap();
+//! // Call the endpoint. The return type decides how to represent the value.
+//! let eod_date: EodData = endpoint.query(&client).unwrap();
+//!
+//! // Some endpoints support pagination. Since Marketstack does pagination through query
+//! // params, we simply specify them in the endpoint builder.
+//! // Note that there are limits defined, and therefore, limit(5) is fallible and returns
+//! // a Result.
+//! let pageable_endpoint = eod::Eod::builder().symbol("AAPL").limit(5)?.build().unwrap();
+//! ```
+
 mod basic;
 mod client;
 mod endpoint;

src/api/common.rs

@@ -24,6 +24,7 @@ impl Default for SortOrder {
     }
 }
 impl SortOrder {
+    /// The string representation of the sort order.
     pub fn as_str(self) -> &'static str {
         match self {
             SortOrder::Ascending => "ASC",

src/api/endpoint.rs

@@ -6,6 +6,7 @@ use serde::de::DeserializeOwned;
 
 use crate::api::{query, ApiError, AsyncClient, AsyncQuery, BodyError, Client, Query, QueryParams};
 
+/// A trait for providing the necessary information for a single REST API endpoint.
 pub trait Endpoint {
     /// The HTTP method to use for the endpoint.
     fn method(&self) -> Method;

src/api/eod.rs

@@ -1,3 +1,5 @@
+//! Implemented endpoints for eod, eod/latest and eod/[date].
+
 use std::collections::BTreeSet;
 
 use chrono::NaiveDate;
@@ -35,6 +37,7 @@ pub struct Eod<'a> {
 }
 
 impl<'a> Eod<'a> {
+    /// Create a builder for the endpoint.
     pub fn builder() -> EodBuilder<'a> {
         EodBuilder::default()
     }
@@ -65,6 +68,7 @@ impl<'a> EodBuilder<'a> {
         self
     }
 
+    /// Limit the number of results returned.
     pub fn limit(&mut self, limit: u16) -> Result<&mut Self, ApiError<PaginationError>> {
         let new = self;
         new.limit = Some(Some(PageLimit::new(limit)?));
@@ -119,6 +123,7 @@ pub struct EodLatest<'a> {
 }
 
 impl<'a> EodLatest<'a> {
+    /// Create a builder for the endpoint.
     pub fn builder() -> EodLatestBuilder<'a> {
         EodLatestBuilder::default()
     }
@@ -149,6 +154,7 @@ impl<'a> EodLatestBuilder<'a> {
         self
     }
 
+    /// Limit the number of results returned.
     pub fn limit(&mut self, limit: u16) -> Result<&mut Self, ApiError<PaginationError>> {
         let new = self;
         new.limit = Some(Some(PageLimit::new(limit)?));
@@ -203,6 +209,7 @@ pub struct EodDate<'a> {
 }
 
 impl<'a> EodDate<'a> {
+    /// Create a builder for the endpoint.
     pub fn builder() -> EodDateBuilder<'a> {
         EodDateBuilder::default()
     }
@@ -233,6 +240,7 @@ impl<'a> EodDateBuilder<'a> {
         self
     }
 
+    /// Limit the number of results returned.
     pub fn limit(&mut self, limit: u16) -> Result<&mut Self, ApiError<PaginationError>> {
         let new = self;
         new.limit = Some(Some(PageLimit::new(limit)?));

src/api/paged.rs

@@ -1,3 +1,8 @@
+//! Pagination related types and functions.
+//!
+//! Pagination is done simply for Marketstack, but this allows setting
+//! page limits to have safety guarantees provided by the new-type pattern.
+
 use thiserror::Error;
 
 use crate::api::ApiError;
@@ -19,9 +24,11 @@ impl PageLimit {
     }
 }
 
+/// Errors which may occur with pagination.
 #[derive(Debug, Error)]
 #[non_exhaustive]
 pub enum PaginationError {
+    /// Pagination exceeds the limit allowed by Marketstack.
     #[error("pagination exceeds limit error")]
     ExceedLimit,
 }