From 6e572d27487ed3d3f077abca6c1023e4155b7402 Mon Sep 17 00:00:00 2001
From: Brandon Dyck <brandon@dyck.us>
Date: Mon, 30 Sep 2024 15:42:26 -0600
Subject: [PATCH] Document State methods

---
 gigaparsec.go | 9 +++++++++
 1 file changed, 9 insertions(+)

diff --git a/gigaparsec.go b/gigaparsec.go
index cf59916..61afd6c 100644
--- a/gigaparsec.go
+++ b/gigaparsec.go
@@ -142,6 +142,13 @@ type State[In any] struct {
 	pos uint64
 }
 
+// Read fills dst with data from this State's position in the underlying source.
+// It returns the number of data it read and a new State for the position at which
+// the read ended, and an error if the read either (1) failed or (2) reached the
+// end of the source before filling dst. All reads from a given State will return
+// data from the same position the source.
+// If the source had too few data left to fill dst, or if the State's position is
+// at or past the end of the source, err will be io.EOF.
 func (s State[In]) Read(dst []In) (n uint64, next State[In], err error) {
 	if s.pos > math.MaxInt64 {
 		return 0, s, io.EOF
@@ -159,10 +166,12 @@ func (s State[In]) Read(dst []In) (n uint64, next State[In], err error) {
 	return uint64(nread), s, err
 }
 
+// Pos returns this State's position.
 func (s State[In]) Pos() uint64 {
 	return s.pos
 }
 
+// At returns a State pointing at pos in the same data source.
 func (s State[In]) At(pos uint64) State[In] {
 	return State[In]{r: s.r, pos: pos}
 }