From 6256b733255380d632aaf783989ec87e7a915c65 Mon Sep 17 00:00:00 2001
From: Brandon Dyck <brandon@dyck.us>
Date: Fri, 13 Sep 2024 19:24:23 -0600
Subject: [PATCH] Document Bind and friends

---
 bind.go                       | 5 +++++
 internal/bindgen/bind.go.tmpl | 2 ++
 2 files changed, 7 insertions(+)

diff --git a/bind.go b/bind.go
index 3f9af6e..b4ce18c 100644
--- a/bind.go
+++ b/bind.go
@@ -2,6 +2,7 @@
 
 package gigaparsec
 
+// Bind combines p with a parser created by f that depends on p's result value.
 func Bind[In, Out, T any](
 	p Parser[In, T],
 	f func(T) Parser[In, Out],
@@ -38,6 +39,7 @@ func Bind[In, Out, T any](
 	}
 }
 
+// Bind2 is equivalent to 2 nested calls to Bind.
 func Bind2[In, Out, T, T2 any](
 	p Parser[In, T],
 	f func(T) Parser[In, T2],
@@ -86,6 +88,7 @@ func Bind2[In, Out, T, T2 any](
 	}
 }
 
+// Bind3 is equivalent to 3 nested calls to Bind.
 func Bind3[In, Out, T, T2, T3 any](
 	p Parser[In, T],
 	f func(T) Parser[In, T2],
@@ -146,6 +149,7 @@ func Bind3[In, Out, T, T2, T3 any](
 	}
 }
 
+// Bind4 is equivalent to 4 nested calls to Bind.
 func Bind4[In, Out, T, T2, T3, T4 any](
 	p Parser[In, T],
 	f func(T) Parser[In, T2],
@@ -218,6 +222,7 @@ func Bind4[In, Out, T, T2, T3, T4 any](
 	}
 }
 
+// Bind5 is equivalent to 5 nested calls to Bind.
 func Bind5[In, Out, T, T2, T3, T4, T5 any](
 	p Parser[In, T],
 	f func(T) Parser[In, T2],
diff --git a/internal/bindgen/bind.go.tmpl b/internal/bindgen/bind.go.tmpl
index b87a525..5566af3 100644
--- a/internal/bindgen/bind.go.tmpl
+++ b/internal/bindgen/bind.go.tmpl
@@ -3,6 +3,8 @@
 {{end}}{{end}}{{end -}}
 
 {{define "func" -}}
+{{if eq . 1}}// Bind combines p with a parser created by f that depends on p's result value.
+{{- else}}// Bind{{.}} is equivalent to {{.}} nested calls to Bind.{{end}}
 func Bind{{.}}[In, Out{{range .Count}}, T{{.}}{{end}} any](
 	p Parser[In, T],
 {{template "fparams" .}}) Parser[In, Out] {