Add comments; increase page buffer size

README.md

@@ -9,19 +9,20 @@ For the moment, *depager* only supports JSON responses.
 interfaces:
 
 ```go
-// The `Page` interface must wrap server responses. This
-// allows pagers to calculate page sizes and iterate over
-// response aggregates.
-//
-// The underlying implementation must be a pointer to a
-// struct containing the desired response fields, all tagged
-// appropriately. Any fields corresponding to
-// platform-specific error responses should also be
-// included.
-//
-// `Count()` must return the total number of items to be
-// paged. `Elems()` must return the items from the current
-// page.
+/* The `Page` interface must wrap server responses. This
+*  allows pagers to calculate page sizes and iterate over
+*  response aggregates.
+*
+*  The underlying implementation must be a pointer to a
+*  struct containing the desired response fields, all tagged
+*  appropriately. Any fields corresponding to
+*  platform-specific error responses should also be
+*  included.
+*
+*  `Count()` must return the total number of items to be
+*  paged. `Elems()` must return the items from the current
+*  page.
+*/
 type Page[T any] interface {
 	Count() uint64
 	Elems() []T

depager.go

@@ -20,26 +20,32 @@ import (
 *  appropriately. Any fields corresponding to
 *  platform-specific error responses should also be
 *  included.
-*
-*  `Count()` must return the total number of items to be
-*  paged. `Elems()` must return the items from the current
-*  page.
  */
 type Page[T any] interface {
+	// Count must return the total number of items to be paged
 	Count() uint64
+
+	// Elems must return the items from the current page
 	Elems() []T
 }
 
+// Exposes the part of the client that depager understands.
 type Client interface {
+	// Get must return the response body and/or an error
 	Get(uri url.URL) ([]byte, error)
 }
 
+// Maps depager's parameters into the API's parameters.
 type PagedURI interface {
+	// PageURI generates a URI to request the indicated items
 	PageURI(limit, offset uint64) url.URL
 }
 
 type Pager[T any] interface {
+	// Iter is intended to be used in a for-range loop
 	Iter() <-chan T
+
+	// LastErr must return the first error encountered, if any
 	LastErr() error
 }
 
@@ -54,7 +60,7 @@ func NewPager[T any](
 		uri:     u,
 		m:       0,
 		n:       pageSize,
-		p:       2,
+		p:       4,
 		newPage: newPage,
 	}
 }