Improving documentation for version v0.2.0 (#19)

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:
 

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<ErrorKind>`] for [`PaginationError`].
+/// Implementation of [`From`]<[`ErrorKind`]> for [`PaginationError`].
 impl From<ErrorKind> for PaginationError {
     fn from(value: ErrorKind) -> Self {
         Self { kind: value }
     }
 }
 
-/// Implementation of [`From<SqlxError>`] 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<sqlx::Error> for PaginationError {
+impl From<SqlxError> for PaginationError {
     fn from(value: sqlx::Error) -> Self {
         Self {
             kind: ErrorKind::SQLxError(value),

page-hunter/src/page_hunter/models.rs

@@ -20,9 +20,9 @@ pub type PaginationResult<E> = Result<E, PaginationError>;
 /// 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<E> Page<E> {
         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<E> Page<E> {
         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<E> {
     sheets: Vec<Page<E>>,
 }
@@ -476,10 +476,10 @@ impl<E> Book<E> {
     /// 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

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:

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<DB>,
@@ -37,7 +37,7 @@ where
     ) -> impl std::future::Future<Output = PaginationResult<Page<S>>>;
 }
 
-/// Implementation of the [`SqlxPagination`] trait for [`QueryBuilder<MySql>`].
+/// 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<Postgres>`].
+/// 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