From 530ce3c4bcd62cf144db0cd48f8f920980db84bf Mon Sep 17 00:00:00 2001 From: Dmitriy Kholkin Date: Sat, 11 Jan 2025 21:20:48 +0300 Subject: [PATCH] documentation changes --- src/api.rs | 3 +++ src/api/anime/user_updates.rs | 2 +- src/api/client.rs | 8 ++++---- src/api/error.rs | 13 +++++++------ src/api/page.rs | 6 ++++-- src/error.rs | 8 ++++---- src/types.rs | 2 ++ 7 files changed, 25 insertions(+), 17 deletions(-) diff --git a/src/api.rs b/src/api.rs index ecef3c3..5dfd74e 100644 --- a/src/api.rs +++ b/src/api.rs @@ -1,3 +1,6 @@ +//! Jikan.moe api wrapper. + +/// `/anime` endpoints. pub mod anime; mod client; mod endpoint; diff --git a/src/api/anime/user_updates.rs b/src/api/anime/user_updates.rs index 388e97f..ec77bfa 100644 --- a/src/api/anime/user_updates.rs +++ b/src/api/anime/user_updates.rs @@ -7,7 +7,7 @@ use crate::api::{ page::Pageable, }; -/// Retrieves a list of users who have added/updated/removed +/// Retrieves a list of users who have added/updated/removed. /// the entry on their list. #[derive(Debug, Clone, Builder)] #[builder(setter(into))] diff --git a/src/api/client.rs b/src/api/client.rs index cd66203..7fc7491 100644 --- a/src/api/client.rs +++ b/src/api/client.rs @@ -12,7 +12,7 @@ use super::error::ApiError; /// A parent trait representing a client which can communicate with jikan.moe pub trait RestClient { - /// The error that may occur for this client + /// The error that may occur for this client. type Error: Error + Send + Sync + 'static; /// Get the URL for the endpoint for the client. @@ -23,7 +23,7 @@ pub trait RestClient { /// A trait representing a blocking client which can communicate with jikan.moe pub trait Client: RestClient { - /// Send a REST query + /// Send a REST query. fn rest( &self, request: RequestBuilder, @@ -31,11 +31,11 @@ pub trait Client: RestClient { ) -> Result, ApiError>; } -/// A trait representing an asynchronous client which can communicate with +/// A trait representing an asynchronous client which can communicate with. /// jikan.moe #[async_trait] pub trait AsyncClient: RestClient { - /// Send a REST query asynchronously + /// Send a REST query asynchronously. async fn rest_async( &self, request: RequestBuilder, diff --git a/src/api/error.rs b/src/api/error.rs index 9415814..bf8ccdd 100644 --- a/src/api/error.rs +++ b/src/api/error.rs @@ -2,7 +2,7 @@ use std::error::Error; use thiserror::Error; -/// Errors from response +/// Errors from response. #[derive(Debug, Error)] pub enum ResponseError { #[error("Parsing JSON: {0}")] @@ -24,7 +24,7 @@ pub enum ResponseError { #[derive(Debug, Error)] #[non_exhaustive] pub enum BodyError { - /// Error serializing body data from form paramaters + /// Error serializing body data from form paramaters. #[error("URL encode error: {0}")] UrlEncoded(#[from] serde_urlencoded::ser::Error), #[error("JSON encode error: {0}")] @@ -38,7 +38,7 @@ pub enum ApiError where E: Error + Send + Sync + 'static, { - /// Error creating body data + /// Error creating body data. #[error("failed to create form data: {0}")] Body(#[from] BodyError), /// The client encountered an error. @@ -47,11 +47,12 @@ where /// The URL failed to parse. #[error("url parse error: {0}")] Parse(#[from] url::ParseError), + /// Error in response. #[error("Error in the HTTP response at url [{url}]: source")] Response { - /// Source of the error + /// Source of the error. source: ResponseError, - /// URL of the error + /// URL of the error. url: http::Uri, }, } @@ -60,7 +61,7 @@ impl ApiError where E: Error + Send + Sync + 'static, { - /// Create an API error from a client error + /// Create an API error from a client error. pub fn client(source: E) -> Self { Self::Client(source) } diff --git a/src/api/page.rs b/src/api/page.rs index 4480a8f..9c1d75b 100644 --- a/src/api/page.rs +++ b/src/api/page.rs @@ -20,7 +20,7 @@ use crate::types::Pagination; /// Marker trait to indicate that an endpoint is pageable. pub trait Pageable {} -// Adapters specific to [`Pageable`] endpoints. +/// Adapters specific to [`Pageable`] endpoints. pub trait PagedEndpointExt<'a, E> { /// Create an Iterator over the results of the paginated endpoint. fn iter(&'a self, client: &'a C) -> PagedIter<'a, E, C, T> @@ -29,10 +29,12 @@ pub trait PagedEndpointExt<'a, E> { T: DeserializeOwned; } +/// Asynchronous iterator over paginated endpoints. pub trait AsyncIterator { + /// The type of the items in this iterator. type Item; - // async fn next(&mut self) -> Option; + /// Advance to the next page of results. fn next(&mut self) -> impl Future> + Send; } diff --git a/src/error.rs b/src/error.rs index f33cff8..424314a 100644 --- a/src/error.rs +++ b/src/error.rs @@ -1,4 +1,4 @@ -//! Error types for the crate +//! Error types for the crate. use thiserror::Error; use crate::api; @@ -13,7 +13,7 @@ pub enum JikanApiError { /// Error from the jikan.moe API #[error("API error: {0}")] Api(#[from] api::ApiError), - /// Error parsing URL + /// Error parsing URL. #[error("url parse error: {0}")] Parse(#[from] url::ParseError), } @@ -22,10 +22,10 @@ pub enum JikanApiError { #[derive(Debug, Error)] #[non_exhaustive] pub enum RestError { - /// Reqwest client error + /// Reqwest client error. #[error("communication: {0}")] Communication(#[from] reqwest::Error), - /// HTTP protocol error + /// HTTP protocol error. #[error("HTTP error: {0}")] Http(#[from] http::Error), } diff --git a/src/types.rs b/src/types.rs index 042efad..fd68f6b 100644 --- a/src/types.rs +++ b/src/types.rs @@ -1,3 +1,5 @@ +//! Helper types for jikan.moe responses. + pub mod anime; mod common;