docs: tidy pagination KDoc and restore strategy rationale comments

Author: OmarAlJarrah

sdk-core/src/main/kotlin/org/dexpace/sdk/core/pagination/AsyncPaginator.kt

@@ -31,7 +31,7 @@ import java.util.function.Consumer
  *
  * Iteration is page-lazy in the same sense as [Paginator]: exactly one HTTP exchange happens
  * per page consumed. A new page is fetched only after the previous page has been drained to
- * the consumer and reports `hasNext` with a non-null next request. Empty pages still count
+ * the consumer and the strategy reports a non-null next request. Empty pages still count
  * toward the [maxPages] budget.
  *
  * ## Termination

sdk-core/src/main/kotlin/org/dexpace/sdk/core/pagination/LinkHeaderPaginationStrategy.kt

@@ -54,8 +54,14 @@ public class LinkHeaderPaginationStrategy<T>
             initialRequest: Request,
         ): PageInfo<T> {
             val items: List<T> = itemsExtractor(response)
+            // Some servers emit multiple `Link` headers (one per link-value) instead of a single
+            // comma-separated header. Joining the values with ',' normalizes both wire shapes into
+            // one string so a single parser handles either. An empty header list joins to "", which
+            // extractNextUrl already maps to null (no `rel="next"`).
             val nextUrlString: String? =
                 extractNextUrl(response.headers.values(linkHeader).joinToString(separator = ","))
+            // A `rel="next"` target that cannot be parsed into a valid URL ends the stream (null)
+            // rather than aborting iteration with a MalformedURLException from resolveNextUrl.
             val nextUrl: URL? =
                 if (nextUrlString.isNullOrEmpty()) null else resolveNextUrl(response, nextUrlString)
             val nextRequest: Request? =

sdk-core/src/main/kotlin/org/dexpace/sdk/core/pagination/PagedIterable.kt

@@ -81,6 +81,5 @@ public class PagedIterable<T>
 
         /** Sequential, ordered, unknown-size [Stream] of every [Page]. */
         @JvmOverloads
-        public fun pageStream(options: PagingOptions = PagingOptions()): Stream<Page<T>> =
-            walker(options).pageStream()
+        public fun pageStream(options: PagingOptions = PagingOptions()): Stream<Page<T>> = walker(options).pageStream()
     }

sdk-core/src/main/kotlin/org/dexpace/sdk/core/pagination/Paginator.kt

@@ -16,37 +16,36 @@ import java.util.stream.Stream
  * Generic, strategy-driven paginator over an [HttpClient].
  *
  * A `Paginator` executes [initialRequest] against [httpClient], delegates response parsing
- * to [strategy], and exposes the resulting stream of items via either [iterateAll] (a lazy
- * `Iterable<T>`) or [streamAll] (a Java 8 `Stream<T>`). Pagination state — cursor,
- * page number, link URL — is derived from each response by the strategy; the paginator
- * itself stays stateless.
+ * to [strategy], and exposes the result two ways: as a stream of items — [iterateAll] (a lazy
+ * `Iterable<T>`) / [streamAll] (a Java 8 `Stream<T>`) — or as a stream of whole pages —
+ * [byPage] (a lazy `Iterable<Page<T>>`) / [pageStream] (a `Stream<Page<T>>`), where each
+ * [Page] carries its items plus per-page status, headers, and request. Pagination state —
+ * cursor, page number, link URL — is derived from each response by the strategy; the
+ * paginator itself stays stateless.
  *
  * ## Laziness
  *
  * Iteration is page-lazy: a new page is fetched only when the consumer pulls past the
  * last item of the current page. Specifically, exactly one HTTP exchange happens per
  * page yielded. No prefetch, no batch fetch — empty pages count toward the fetch budget,
- * but advancing past an exhausted page with `hasNext = false` does not trigger a fetch.
+ * but advancing past a page whose strategy returned a null next request does not trigger a fetch.
  *
  * ## Termination
  *
  * The iterator terminates when either:
  *
- * - the current page's items are exhausted AND `page.hasNext == false`, or
- * - the current page's items are exhausted AND `page.nextPageRequest()` returned `null`, or
+ * - the current page's items are exhausted AND the strategy returned a `PageInfo` with a
+ *   `null` next request (end of stream), or
  * - [maxPages] pages have already been fetched (the safety cap).
  *
- * The first two conditions are semantically distinct but produce the same outcome: end of
- * stream.
- *
  * ## Safety cap
  *
  * [maxPages] defaults to `Long.MAX_VALUE` (effectively unbounded, matching `Iterable`
  * semantics). A misbehaving server that returns the same `rel="next"` link — or any other
  * unchanging paging cursor — on every page would otherwise drive an unbounded fetch loop.
  * **Production callers should set a finite cap.** Once [maxPages] pages have been yielded the
- * iterator stops fetching, even if the last page still reports `hasNext`. The cap counts
- * pages fetched (HTTP exchanges), not items.
+ * iterator stops fetching, even if the strategy still reports a non-null next request. The cap
+ * counts pages fetched (HTTP exchanges), not items.
  *
  * ## Response lifecycle
  *

sdk-core/src/test/kotlin/org/dexpace/sdk/core/pagination/PageTest.kt

@@ -1,3 +1,10 @@
+/*
+ * Copyright (c) 2026 dexpace and Omar Aljarrah
+ *
+ * Licensed under the MIT License. See LICENSE in the project root.
+ * SPDX-License-Identifier: MIT
+ */
+
 package org.dexpace.sdk.core.pagination
 
 import org.dexpace.sdk.core.http.common.Headers
@@ -17,33 +24,47 @@ import kotlin.test.assertNull
 class PageTest {
     @BeforeTest fun setup() = installIoProvider()
 
-    private fun request(): Request = Request.builder().method(Method.GET).url(URL("https://api.example.com/items")).build()
+    private fun request(): Request =
+        Request.builder().method(
+            Method.GET,
+        ).url(URL("https://api.example.com/items")).build()
 
     @Test
     fun `explicit constructor exposes fields and defaults links to null`() {
-        val page = Page(items = listOf("a", "b"), statusCode = 200, headers = Headers.builder().build(), request = request())
+        val page =
+            Page(items = listOf("a", "b"), statusCode = 200, headers = Headers.builder().build(), request = request())
         assertEquals(listOf("a", "b"), page.items)
         assertEquals(200, page.statusCode)
         assertNull(page.nextLink)
         assertNull(page.continuationToken)
+        assertNull(page.firstLink)
+        assertNull(page.previousLink)
+        assertNull(page.lastLink)
     }
 
     @Test
     fun `from snapshots status, headers and request and does not close the response`() {
         val closeCount = AtomicInteger(0)
-        val body = object : ResponseBody() {
-            override fun mediaType() = null
-            override fun contentLength() = -1L
-            override fun source() = throw UnsupportedOperationException("not needed")
-            override fun close() { closeCount.incrementAndGet() }
-        }
-        val response = Response.builder()
-            .request(request())
-            .protocol(Protocol.HTTP_1_1)
-            .status(Status.fromCode(204))
-            .headers(Headers.builder().add("X-Total", "9").build())
-            .body(body)
-            .build()
+        val body =
+            object : ResponseBody() {
+                override fun mediaType() = null
+
+                override fun contentLength() = -1L
+
+                override fun source() = throw UnsupportedOperationException("not needed")
+
+                override fun close() {
+                    closeCount.incrementAndGet()
+                }
+            }
+        val response =
+            Response.builder()
+                .request(request())
+                .protocol(Protocol.HTTP_1_1)
+                .status(Status.fromCode(204))
+                .headers(Headers.builder().add("X-Total", "9").build())
+                .body(body)
+                .build()
 
         val page = Page.from(response, items = listOf(1, 2, 3), nextLink = "https://api.example.com/items?page=2")
 

sdk-core/src/test/kotlin/org/dexpace/sdk/core/pagination/PageWalkerTest.kt

@@ -26,7 +26,11 @@ class PageWalkerTest {
     @Test
     fun `maxPages caps the number of pages yielded`() {
         var produced = 0
-        val walker = PageWalker({ produced++; page("x$produced") }, maxPages = 2)
+        val walker =
+            PageWalker({
+                produced++
+                page("x$produced")
+            }, maxPages = 2)
         val collected = walker.pages().asSequence().toList()
         assertEquals(2, collected.size)
         assertEquals(2, produced) // never fetches a third page

sdk-core/src/test/kotlin/org/dexpace/sdk/core/pagination/PaginatorByPageTest.kt

@@ -46,6 +46,18 @@ class PaginatorByPageTest {
         assertEquals(listOf("a", "b"), pages[0].items)
         assertEquals(listOf("c"), pages[1].items)
         assertEquals(200, pages[0].statusCode)
+        assertEquals(200, pages[1].statusCode)
+        assertEquals(2, client.callCount)
+    }
+
+    @Test
+    fun `pageStream yields one page per HTTP exchange`() {
+        val client = StubHttpClient()
+        client.on("https://api.example.com/items") { req -> textResponse(req, "items=a,b\ncursor=abc") }
+        client.on("https://api.example.com/items?cursor=abc") { req -> textResponse(req, "items=c\ncursor=") }
+        val paginator = Paginator(client, initialRequest(), CursorPaginationStrategy(extractor, "cursor"))
+
+        assertEquals(2L, paginator.pageStream().count())
         assertEquals(2, client.callCount)
     }
 }