From 0a4f10ea2671d0af74f2bbdee79f83d800771eda Mon Sep 17 00:00:00 2001 From: Reuben Wong Date: Fri, 20 Oct 2023 00:20:38 +0800 Subject: [PATCH] Add all missing docs --- src/api.rs | 44 ++++++++++++++++++++++++++++++++++++++++++++ src/api/common.rs | 1 + src/api/endpoint.rs | 1 + src/api/eod.rs | 8 ++++++++ src/api/paged.rs | 7 +++++++ 5 files changed, 61 insertions(+) diff --git a/src/api.rs b/src/api.rs index a958c74..1387584 100644 --- a/src/api.rs +++ b/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, +//! } +//! +//! // 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; diff --git a/src/api/common.rs b/src/api/common.rs index 9c35544..dabc9c7 100644 --- a/src/api/common.rs +++ b/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", diff --git a/src/api/endpoint.rs b/src/api/endpoint.rs index 6fd84c0..650cb3a 100644 --- a/src/api/endpoint.rs +++ b/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; diff --git a/src/api/eod.rs b/src/api/eod.rs index 182af6a..80078d8 100644 --- a/src/api/eod.rs +++ b/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> { 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> { 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> { let new = self; new.limit = Some(Some(PageLimit::new(limit)?)); diff --git a/src/api/paged.rs b/src/api/paged.rs index 1a03cfd..4a6e33a 100644 --- a/src/api/paged.rs +++ b/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, }