From fb6b09c263cbef4ae6b57f1dad155dab5fc6df87 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?No=C3=A9=20Costa?= <noe.costa@icinga.com>
Date: Fri, 12 Apr 2024 14:12:55 +0200
Subject: [PATCH] docs(add-paging-to-result-set): improved PHPDocs

---
 src/ResultSet.php | 27 +++++++++++++++++++--------
 1 file changed, 19 insertions(+), 8 deletions(-)

diff --git a/src/ResultSet.php b/src/ResultSet.php
index 0a6da94..be71ac4 100644
--- a/src/ResultSet.php
+++ b/src/ResultSet.php
@@ -35,6 +35,8 @@ class ResultSet implements Iterator
     protected $pageSize;
 
     /**
+     * Construct the {@see self::class class} object
+     *
      * @param Traversable $traversable
      * @param ?int $limit
      * @param ?int $offset
@@ -48,10 +50,13 @@ public function __construct(Traversable $traversable, $limit = null, $offset = n
     }
 
     /**
-     * Returns the current page calculated from the {@see ResultSet::$offset} and the {@see ResultSet::$pageSize}
+     * Get the current page number
+     *
+     * Returns the current page, calculated by the {@see self::$position position}, {@see self::$offset offset}
+     * and the {@see self::$pageSize page size}
      *
-     * @return int
-     * @throws BadMethodCallException if no {@see ResultSet::$pageSize} has been provided
+     * @return int page
+     * @throws BadMethodCallException if no {@see self::$pageSize page size} has been provided
      */
     public function getCurrentPage(): int
     {
@@ -65,13 +70,13 @@ public function getCurrentPage(): int
             return 1;
         }
 
-        throw new BadMethodCallException(`The 'pageSize' property has not been set. Cannot calculate pages.`);
+        throw new BadMethodCallException("The 'pageSize' property has not been set. Cannot calculate pages.");
     }
 
     /**
-     * Sets the amount of items a page should contain (needed for pagination)
+     * Set the amount of entries a page should contain (needed for pagination)
      *
-     * @param ?int $size
+     * @param ?int $size entries per  page
      * @return $this
      */
     public function setPageSize(?int $size)
@@ -82,7 +87,7 @@ public function setPageSize(?int $size)
     }
 
     /**
-     * Create a new result set from the given query
+     * Create a new result set from the given {@see Query query}
      *
      * @param Query $query
      *
@@ -96,7 +101,7 @@ public static function fromQuery(Query $query)
     /**
      * Do not cache query result
      *
-     * ResultSet instance can only be iterated once
+     * {@see self::class class} instance can only be iterated once
      *
      * @return $this
      */
@@ -108,6 +113,8 @@ public function disableCache()
     }
 
     /**
+     * Check if dataset has more entries
+     *
      * @return bool
      */
     public function hasMore()
@@ -116,6 +123,8 @@ public function hasMore()
     }
 
     /**
+     * Check if dataset has a result
+     *
      * @return bool
      */
     public function hasResult()
@@ -199,6 +208,8 @@ protected function advance()
     }
 
     /**
+     * Yield entry from dataset
+     *
      * @param Traversable $traversable
      * @return Generator
      */