From 24770c2e2a110ef5e31483aa7aff380a5b34221e Mon Sep 17 00:00:00 2001 From: JMTamayo Date: Sat, 1 Jun 2024 08:18:06 -0500 Subject: [PATCH] Improving documentation for version v0.2.0 --- page-hunter/CHANGELOG.md | 2 +- page-hunter/src/page_hunter/errors.rs | 8 ++++---- page-hunter/src/page_hunter/models.rs | 20 +++++++++---------- .../src/page_hunter/records_pagination.rs | 6 +++--- .../src/page_hunter/sqlx_pagination.rs | 20 +++++++++---------- 5 files changed, 28 insertions(+), 28 deletions(-) diff --git a/page-hunter/CHANGELOG.md b/page-hunter/CHANGELOG.md index 7878bd4..c24aab6 100644 --- a/page-hunter/CHANGELOG.md +++ b/page-hunter/CHANGELOG.md @@ -5,7 +5,7 @@ All notable changes to this project will be documented in this file. The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). -## 🚀 v0.2.0 [2024-XX-XX] +## 🚀 v0.2.0 [2024-06-01] ### Added: diff --git a/page-hunter/src/page_hunter/errors.rs b/page-hunter/src/page_hunter/errors.rs index 0045b7f..8d6cf1a 100644 --- a/page-hunter/src/page_hunter/errors.rs +++ b/page-hunter/src/page_hunter/errors.rs @@ -22,7 +22,7 @@ impl ErrorKind { matches!(self, ErrorKind::FieldValueError(_)) } - /// Check if the [`ErrorKind`] is a [`ErrorKind::DatabaseError`]. Only available when the `pg-sqlx` or `mysql-sqlx` features are enabled. + /// Check if the [`ErrorKind`] is a [`ErrorKind::SQLxError`]. Only available when the `pg-sqlx` or `mysql-sqlx` features are enabled. #[cfg(any(feature = "pg-sqlx", feature = "mysql-sqlx"))] pub fn is_sqlx_error(&self) -> bool { matches!(self, ErrorKind::SQLxError(_)) @@ -79,16 +79,16 @@ impl Debug for PaginationError { } } -/// Implementation of [`From`] for [`PaginationError`]. +/// Implementation of [`From`]<[`ErrorKind`]> for [`PaginationError`]. impl From for PaginationError { fn from(value: ErrorKind) -> Self { Self { kind: value } } } -/// Implementation of [`From`] for [`PaginationError`]. Only available when the `pg-sqlx` or `mysql-sqlx` features are enabled. +/// Implementation of [`From`]<[`sqlx::Error`]> for [`PaginationError`]. Only available when the `pg-sqlx` or `mysql-sqlx` features are enabled. #[cfg(any(feature = "pg-sqlx", feature = "mysql-sqlx"))] -impl From for PaginationError { +impl From for PaginationError { fn from(value: sqlx::Error) -> Self { Self { kind: ErrorKind::SQLxError(value), diff --git a/page-hunter/src/page_hunter/models.rs b/page-hunter/src/page_hunter/models.rs index 25349fd..477aca1 100644 --- a/page-hunter/src/page_hunter/models.rs +++ b/page-hunter/src/page_hunter/models.rs @@ -20,9 +20,9 @@ pub type PaginationResult = Result; /// Model to represent paginated items. /// /// #### Fields: -/// - **items**: Represents the ***items*** in a [`Page`] as a [`Vec`] of generic elements ***E***. +/// - **items**: Represents the items in a [`Page`] as a [`Vec`] of `E`. /// - **page**: Represents the page index in a [`Page`]. It starts from 0 to ***pages*** - 1. -/// - **size**: Represents the maximum number of elements per [`Page`]. ***items*** length must be equal to ***size** value for all pages except the last page, when ***items*** length could be less than or equal to ***size***. +/// - **size**: Represents the maximum number of elements per [`Page`]. ***items*** length must be equal to ***size*** for all pages except the last page, when ***items*** length could be less than or equal to ***size***. /// - **total**: Represents the total number of records used for pagination. /// - **pages**: Represents the total number of pages required for paginate the items. /// - **previous_page**: Represents the previous page index in a [`Page`]. If there is no previous page, it will be [`None`]. @@ -73,13 +73,13 @@ impl Page { self.next_page } - /// Verify [`Page`] fields. It returns a [`PaginationResult`] with ***()*** if successful, otherwise a [`PaginationError`] is returned. + /// Verify [`Page`] fields. /// /// ### Arguments: /// *No arguments* /// /// ### Returns: - /// A [`PaginationResult`] with ***()*** if successful, otherwise a [`PaginationError`] is returned. + /// A [`PaginationResult`] with a `()` if successful, otherwise a [`PaginationError`] is returned. /// /// This method is used to check if the fields of a [`Page`] are valid based on the following criteria: /// - ***pages*** must be equal to ***total*** divided by ***size*** rounded up. When ***size*** is 0, ***pages*** must be 1. @@ -167,16 +167,16 @@ impl Page { Ok(()) } - /// Create a new [`Page`] instance. It returns a [`PaginationResult`] with a [`Page`] if successful, otherwise a [`PaginationError`] is returned. + /// Create a new [`Page`] instance. /// /// ### Arguments: - /// - **items**: A reference to a collection of items `E`, where `E` implements [`Clone`] and [`Debug`]. + /// - **items**: A reference to a collection of items `E`, where `E` must implement [`Clone`]. /// - **page**: The page index. /// - **size**: The maximum number of elements per page. /// - **total**: The total number of records used for pagination. /// /// ### Returns: - /// A [`PaginationResult`] with a [`Page`] of the paginated items ***E*** if successful, otherwise a [`PaginationError`] is returned. + /// A [`PaginationResult`] with a [`Page`] if successful, otherwise a [`PaginationError`] is returned. /// /// ### Example: ///```rust,no_run @@ -462,7 +462,7 @@ where /// Model to represent a book of paginated items. /// #### Fields: -/// - **sheets**: Represents the ***sheets*** in a [`Book`] as a [`Vec`] of [`Page`] of generic elements ***E***. +/// - **sheets**: Represents the ***sheets*** in a [`Book`] as a [`Vec`] of [`Page`]. pub struct Book { sheets: Vec>, } @@ -476,10 +476,10 @@ impl Book { /// Create a new [`Book`] instance. /// /// ### Arguments: - /// - **sheets**: A reference to a collection of [`Page`] of items `E`, where `E` implements [`Clone`] and [`Debug`]. + /// - **sheets**: A reference to a [`Vec`] of [`Page`], where `E` must implement [`Clone`]. /// /// ### Returns: - /// A [`Book`] of the paginated items ***E*** if successful, otherwise a [`PaginationError`] is returned. + /// A [`Book`] if successful, otherwise a [`PaginationError`] is returned. /// /// ### Example: /// ```rust,no_run diff --git a/page-hunter/src/page_hunter/records_pagination.rs b/page-hunter/src/page_hunter/records_pagination.rs index 509f094..afbd514 100644 --- a/page-hunter/src/page_hunter/records_pagination.rs +++ b/page-hunter/src/page_hunter/records_pagination.rs @@ -3,8 +3,8 @@ use super::models::*; /// Paginate records into a [`Page`] model. /// /// #### Arguments: -/// - **records**: A reference to a collection of records `R`, where `R` implements [`IntoIterator`] and [`Clone`], and `R::Item` implements [`Clone`]. -/// - **page**: The page number. +/// - **records**: A reference to a collection of records `R`, where `R` must implement [`IntoIterator`] and [`Clone`], and `R::Item` must implement [`Clone`]. +/// - **page**: The page index. /// - **size**: The number of records per page. /// /// #### Returns: @@ -46,7 +46,7 @@ where /// Bind records into a [`Book`] model. /// /// #### Arguments: -/// - **records**: A reference to a collection of records `R`, where `R` implements [`IntoIterator`] and [`Clone`], and `R::Item` implements [`Clone`]. +/// - **records**: A reference to a collection of records `R`, where `R` must implement [`IntoIterator`] and [`Clone`], and `R::Item` must implement [`Clone`]. /// - **size**: The number of records per page. /// /// #### Returns: diff --git a/page-hunter/src/page_hunter/sqlx_pagination.rs b/page-hunter/src/page_hunter/sqlx_pagination.rs index ca71ac1..53665ae 100644 --- a/page-hunter/src/page_hunter/sqlx_pagination.rs +++ b/page-hunter/src/page_hunter/sqlx_pagination.rs @@ -18,17 +18,17 @@ where S: for<'r> FromRow<'r, DB::Row> + Clone, { /// Paginate results from a SQL query into a [`Page`] model from database using [`sqlx`]. - /// Available for PostgreSQL, MySQL and SQLite databases. + /// Available for PostgreSQL and MySQL databases. /// /// ### Arguments: - /// - **pool**: A reference to a [`Pool`] of DB instance, where DB implements the [`Database`] trait. - /// - **page**: The page number. + /// - **pool**: A reference to a [`Pool`] of DB instance, where DB must implement the [`Database`] trait. + /// - **page**: The page index. /// - **size**: The number of records per page. /// /// ### Returns: - /// A [`PaginationResult`] containing a [`Page`] model of the paginated records `S`, where `S` is a struct that implements the [`FromRow`] trait for given [`Database::Row`] type according to the database. + /// A [`PaginationResult`] containing a [`Page`] model of the paginated records `S`, where `S` must implement the [`FromRow`] for given [`Database::Row`] type according to the database. /// - /// Only available when the `pg-sqlx`, `mysql-sqlx` or `sqlite-sqlx` features are enabled. + /// Only available when the `pg-sqlx` or `mysql-sqlx` features are enabled. fn paginate<'p>( &self, pool: &'p Pool, @@ -37,7 +37,7 @@ where ) -> impl std::future::Future>>; } -/// Implementation of the [`SqlxPagination`] trait for [`QueryBuilder`]. +/// Implementation of [`SQLxPagination`] for [`QueryBuilder`]<[`MySql`]>. /// /// At first, this function calculates the total number of records in the query result by executing a COUNT(*) query. Then, it fetches the records for the requested page and size by executing the original query with a LIMIT and OFFSET clause. /// @@ -65,11 +65,11 @@ where /// /// #### Arguments: /// - **pool**: A reference to a [`MySqlPool`] instance. -/// - **page**: The page number. +/// - **page**: The page index. /// - **size**: The number of records per page. /// /// #### Returns: -/// A [`PaginationResult`] containing a [`Page`] model of the paginated records `S`, where `S` is a struct that implements the [`FromRow`] trait for the [`MySql`] struct. +/// A [`PaginationResult`] containing a [`Page`] model of the paginated records `S`, where `S` must implement [`FromRow`] for [`MySqlRow`]. /// /// ### Example: /// ```rust,no_run @@ -146,7 +146,7 @@ where } } -/// Implementation of the [`SqlxPagination`] trait for [`QueryBuilder`]. +/// Implementation of the [`SQLxPagination`] trait for [`QueryBuilder`]<[`Postgres`]>. /// /// At first, this function calculates the total number of records in the query result by executing a COUNT(*) query. Then, it fetches the records for the requested page and size by executing the original query with a LIMIT and OFFSET clause. /// @@ -178,7 +178,7 @@ where /// - **size**: The number of records per page. /// /// #### Returns: -/// A [`PaginationResult`] containing a [`Page`] model of the paginated records `S`, where `S` is a struct that implements the [`FromRow`] trait for the [`PgRow`] struct. +/// A [`PaginationResult`] containing a [`Page`] model of the paginated records `S`, where `S` must implement [`FromRow`] for [`PgRow`]. /// /// ### Example: /// ```rust,no_run