Add doc.go and fix some documentation issues in generation template (#11

)

README.md

@@ -2,6 +2,7 @@
 
 [![Go](https://github.com/barweiss/go-tuple/actions/workflows/go.yml/badge.svg)](https://github.com/barweiss/go-tuple/actions/workflows/go.yml)
 [![Coverage Status](https://coveralls.io/repos/github/barweiss/go-tuple/badge.svg)](https://coveralls.io/github/barweiss/go-tuple)
+[![Go Reference](https://pkg.go.dev/badge/github.com/barweiss/go-tuple.svg)](https://pkg.go.dev/github.com/barweiss/go-tuple)
 
 Go 1.18 tuple implementation.
 

doc.go

@@ -0,0 +1,36 @@
+// package tuple defines tuple types that can hold multiple values of varying types. Currently, tuples with up to 9 values are supported.
+//
+// Tuple methods:
+//
+// - Len returns the number of values held by the tuple.
+// - Values returns the values held by the tuple.
+// - Array returns an array of the tuple values.
+// - Slice returns a slice of the tuple values.
+// - String returns the string representation of the tuple.
+// - GoString returns a Go-syntax representation of the tuple.
+//
+// Tuple creation functions:
+//
+// - New<N> creates a new tuple holding N generic values.
+// - FromArray<N> returns a tuple from an array of length N.
+// If any of the values can not be converted to the generic type, an error is returned.
+// - FromArray<N>X returns a tuple from an array of length N.
+// If any of the values can not be converted to the generic type, the function panics.
+// - FromSlice<N> returns a tuple from a slice of length N.
+// If the length of the slice doesn't match, or any of the values can not be converted to the generic type, an error is returned.
+// - FromSlice<N>X returns a tuple from a slice of length N.
+// If the length of the slice doesn't match, or any of the values can not be converted to the generic type, the function panics.
+//
+// Tuple comparison functions:
+//
+// - Equal<N> returns whether the host tuple is equal to the other tuple.
+// - Compare<N> returns whether the host tuple is semantically less than, equal to, or greater than the guest tuple.
+// - LessThan<N> returns whether the host tuple is semantically less than the guest tuple.
+// - LessOrEqual<N> returns whether the host tuple is semantically less than or equal to the guest tuple.
+// - GreaterThan<N> returns whether the host tuple is semantically greater than the guest tuple.
+// - GreaterOrEqual<N> returns whether the host tuple is semantically greater than or equal to the guest tuple.
+//
+// Tuple comparison functions may have an "C" or "E" suffix as overload with additional supported type constraints.
+// Comparison functions ending with "C" accept the "Comparable" constraint.
+// Comparison functions ending with "E" accept the "Equalable contraint.
+package tuple

scripts/gen/tuple.tpl

@@ -188,42 +188,42 @@ func LessThan{{.Len}}C[{{genericTypesDeclGenericConstraint .Indexes "Comparable"
  return Compare{{.Len}}C(host, guest).LT()
 }
 
-// LessOrEqual{{.Len}} returns whether the host tuple is semantically less than the guest tuple.
+// LessOrEqual{{.Len}} returns whether the host tuple is semantically less than or equal to the guest tuple.
 // All tuple elements of the host and guest parameters must match the "Ordered" constraint.
 // To compare tuples that hold custom comparable values, use the LessOrEqual{{.Len}}C function.
 func LessOrEqual{{.Len}}[{{genericTypesDecl .Indexes "constraints.Ordered"}}](host, guest T{{.Len}}[{{.GenericTypesForward}}]) bool {
  return Compare{{.Len}}(host, guest).LE()
 }
 
-// LessOrEqual{{.Len}}C returns whether the host tuple is semantically less than the guest tuple.
+// LessOrEqual{{.Len}}C returns whether the host tuple is semantically less than or equal to the guest tuple.
 // All tuple elements of the host and guest parameters must match the Comparable constraint.
 // To compare tuples that hold built-in "Ordered" values, use the LessOrEqual{{.Len}} function.
 func LessOrEqual{{.Len}}C[{{genericTypesDeclGenericConstraint .Indexes "Comparable"}}](host, guest T{{.Len}}[{{.GenericTypesForward}}]) bool {
  return Compare{{.Len}}C(host, guest).LE()
 }
 
-// GreaterThan{{.Len}} returns whether the host tuple is semantically less than the guest tuple.
+// GreaterThan{{.Len}} returns whether the host tuple is semantically greater than the guest tuple.
 // All tuple elements of the host and guest parameters must match the "Ordered" constraint.
 // To compare tuples that hold custom comparable values, use the GreaterThan{{.Len}}C function.
 func GreaterThan{{.Len}}[{{genericTypesDecl .Indexes "constraints.Ordered"}}](host, guest T{{.Len}}[{{.GenericTypesForward}}]) bool {
  return Compare{{.Len}}(host, guest).GT()
 }
 
-// GreaterThan{{.Len}}C returns whether the host tuple is semantically less than the guest tuple.
+// GreaterThan{{.Len}}C returns whether the host tuple is semantically greater than the guest tuple.
 // All tuple elements of the host and guest parameters must match the Comparable constraint.
 // To compare tuples that hold built-in "Ordered" values, use the GreaterThan{{.Len}} function.
 func GreaterThan{{.Len}}C[{{genericTypesDeclGenericConstraint .Indexes "Comparable"}}](host, guest T{{.Len}}[{{.GenericTypesForward}}]) bool {
  return Compare{{.Len}}C(host, guest).GT()
 }
 
-// GreaterOrEqual{{.Len}} returns whether the host tuple is semantically less than the guest tuple.
+// GreaterOrEqual{{.Len}} returns whether the host tuple is semantically greater than or equal to the guest tuple.
 // All tuple elements of the host and guest parameters must match the "Ordered" constraint.
 // To compare tuples that hold custom comparable values, use the GreaterOrEqual{{.Len}}C function.
 func GreaterOrEqual{{.Len}}[{{genericTypesDecl .Indexes "constraints.Ordered"}}](host, guest T{{.Len}}[{{.GenericTypesForward}}]) bool {
  return Compare{{.Len}}(host, guest).GE()
 }
 
-// GreaterOrEqual{{.Len}}C returns whether the host tuple is semantically less than the guest tuple.
+// GreaterOrEqual{{.Len}}C returns whether the host tuple is semantically greater than or equal to the guest tuple.
 // All tuple elements of the host and guest parameters must match the Comparable constraint.
 // To compare tuples that hold built-in "Ordered" values, use the GreaterOrEqual{{.Len}} function.
 func GreaterOrEqual{{.Len}}C[{{genericTypesDeclGenericConstraint .Indexes "Comparable"}}](host, guest T{{.Len}}[{{.GenericTypesForward}}]) bool {

tuple1.go

@@ -153,42 +153,42 @@ func LessThan1C[Ty1 Comparable[Ty1]](host, guest T1[Ty1]) bool {
  return Compare1C(host, guest).LT()
 }
 
-// LessOrEqual1 returns whether the host tuple is semantically less than the guest tuple.
+// LessOrEqual1 returns whether the host tuple is semantically less than or equal to the guest tuple.
 // All tuple elements of the host and guest parameters must match the "Ordered" constraint.
 // To compare tuples that hold custom comparable values, use the LessOrEqual1C function.
 func LessOrEqual1[Ty1 constraints.Ordered](host, guest T1[Ty1]) bool {
  return Compare1(host, guest).LE()
 }
 
-// LessOrEqual1C returns whether the host tuple is semantically less than the guest tuple.
+// LessOrEqual1C returns whether the host tuple is semantically less than or equal to the guest tuple.
 // All tuple elements of the host and guest parameters must match the Comparable constraint.
 // To compare tuples that hold built-in "Ordered" values, use the LessOrEqual1 function.
 func LessOrEqual1C[Ty1 Comparable[Ty1]](host, guest T1[Ty1]) bool {
  return Compare1C(host, guest).LE()
 }
 
-// GreaterThan1 returns whether the host tuple is semantically less than the guest tuple.
+// GreaterThan1 returns whether the host tuple is semantically greater than the guest tuple.
 // All tuple elements of the host and guest parameters must match the "Ordered" constraint.
 // To compare tuples that hold custom comparable values, use the GreaterThan1C function.
 func GreaterThan1[Ty1 constraints.Ordered](host, guest T1[Ty1]) bool {
  return Compare1(host, guest).GT()
 }
 
-// GreaterThan1C returns whether the host tuple is semantically less than the guest tuple.
+// GreaterThan1C returns whether the host tuple is semantically greater than the guest tuple.
 // All tuple elements of the host and guest parameters must match the Comparable constraint.
 // To compare tuples that hold built-in "Ordered" values, use the GreaterThan1 function.
 func GreaterThan1C[Ty1 Comparable[Ty1]](host, guest T1[Ty1]) bool {
  return Compare1C(host, guest).GT()
 }
 
-// GreaterOrEqual1 returns whether the host tuple is semantically less than the guest tuple.
+// GreaterOrEqual1 returns whether the host tuple is semantically greater than or equal to the guest tuple.
 // All tuple elements of the host and guest parameters must match the "Ordered" constraint.
 // To compare tuples that hold custom comparable values, use the GreaterOrEqual1C function.
 func GreaterOrEqual1[Ty1 constraints.Ordered](host, guest T1[Ty1]) bool {
  return Compare1(host, guest).GE()
 }
 
-// GreaterOrEqual1C returns whether the host tuple is semantically less than the guest tuple.
+// GreaterOrEqual1C returns whether the host tuple is semantically greater than or equal to the guest tuple.
 // All tuple elements of the host and guest parameters must match the Comparable constraint.
 // To compare tuples that hold built-in "Ordered" values, use the GreaterOrEqual1 function.
 func GreaterOrEqual1C[Ty1 Comparable[Ty1]](host, guest T1[Ty1]) bool {

tuple2.go

@@ -169,42 +169,42 @@ func LessThan2C[Ty1 Comparable[Ty1], Ty2 Comparable[Ty2]](host, guest T2[Ty1, Ty
  return Compare2C(host, guest).LT()
 }
 
-// LessOrEqual2 returns whether the host tuple is semantically less than the guest tuple.
+// LessOrEqual2 returns whether the host tuple is semantically less than or equal to the guest tuple.
 // All tuple elements of the host and guest parameters must match the "Ordered" constraint.
 // To compare tuples that hold custom comparable values, use the LessOrEqual2C function.
 func LessOrEqual2[Ty1, Ty2 constraints.Ordered](host, guest T2[Ty1, Ty2]) bool {
  return Compare2(host, guest).LE()
 }
 
-// LessOrEqual2C returns whether the host tuple is semantically less than the guest tuple.
+// LessOrEqual2C returns whether the host tuple is semantically less than or equal to the guest tuple.
 // All tuple elements of the host and guest parameters must match the Comparable constraint.
 // To compare tuples that hold built-in "Ordered" values, use the LessOrEqual2 function.
 func LessOrEqual2C[Ty1 Comparable[Ty1], Ty2 Comparable[Ty2]](host, guest T2[Ty1, Ty2]) bool {
  return Compare2C(host, guest).LE()
 }
 
-// GreaterThan2 returns whether the host tuple is semantically less than the guest tuple.
+// GreaterThan2 returns whether the host tuple is semantically greater than the guest tuple.
 // All tuple elements of the host and guest parameters must match the "Ordered" constraint.
 // To compare tuples that hold custom comparable values, use the GreaterThan2C function.
 func GreaterThan2[Ty1, Ty2 constraints.Ordered](host, guest T2[Ty1, Ty2]) bool {
  return Compare2(host, guest).GT()
 }
 
-// GreaterThan2C returns whether the host tuple is semantically less than the guest tuple.
+// GreaterThan2C returns whether the host tuple is semantically greater than the guest tuple.
 // All tuple elements of the host and guest parameters must match the Comparable constraint.
 // To compare tuples that hold built-in "Ordered" values, use the GreaterThan2 function.
 func GreaterThan2C[Ty1 Comparable[Ty1], Ty2 Comparable[Ty2]](host, guest T2[Ty1, Ty2]) bool {
  return Compare2C(host, guest).GT()
 }
 
-// GreaterOrEqual2 returns whether the host tuple is semantically less than the guest tuple.
+// GreaterOrEqual2 returns whether the host tuple is semantically greater than or equal to the guest tuple.
 // All tuple elements of the host and guest parameters must match the "Ordered" constraint.
 // To compare tuples that hold custom comparable values, use the GreaterOrEqual2C function.
 func GreaterOrEqual2[Ty1, Ty2 constraints.Ordered](host, guest T2[Ty1, Ty2]) bool {
  return Compare2(host, guest).GE()
 }
 
-// GreaterOrEqual2C returns whether the host tuple is semantically less than the guest tuple.
+// GreaterOrEqual2C returns whether the host tuple is semantically greater than or equal to the guest tuple.
 // All tuple elements of the host and guest parameters must match the Comparable constraint.
 // To compare tuples that hold built-in "Ordered" values, use the GreaterOrEqual2 function.
 func GreaterOrEqual2C[Ty1 Comparable[Ty1], Ty2 Comparable[Ty2]](host, guest T2[Ty1, Ty2]) bool {

tuple3.go

@@ -185,42 +185,42 @@ func LessThan3C[Ty1 Comparable[Ty1], Ty2 Comparable[Ty2], Ty3 Comparable[Ty3]](h
  return Compare3C(host, guest).LT()
 }
 
-// LessOrEqual3 returns whether the host tuple is semantically less than the guest tuple.
+// LessOrEqual3 returns whether the host tuple is semantically less than or equal to the guest tuple.
 // All tuple elements of the host and guest parameters must match the "Ordered" constraint.
 // To compare tuples that hold custom comparable values, use the LessOrEqual3C function.
 func LessOrEqual3[Ty1, Ty2, Ty3 constraints.Ordered](host, guest T3[Ty1, Ty2, Ty3]) bool {
  return Compare3(host, guest).LE()
 }
 
-// LessOrEqual3C returns whether the host tuple is semantically less than the guest tuple.
+// LessOrEqual3C returns whether the host tuple is semantically less than or equal to the guest tuple.
 // All tuple elements of the host and guest parameters must match the Comparable constraint.
 // To compare tuples that hold built-in "Ordered" values, use the LessOrEqual3 function.
 func LessOrEqual3C[Ty1 Comparable[Ty1], Ty2 Comparable[Ty2], Ty3 Comparable[Ty3]](host, guest T3[Ty1, Ty2, Ty3]) bool {
  return Compare3C(host, guest).LE()
 }
 
-// GreaterThan3 returns whether the host tuple is semantically less than the guest tuple.
+// GreaterThan3 returns whether the host tuple is semantically greater than the guest tuple.
 // All tuple elements of the host and guest parameters must match the "Ordered" constraint.
 // To compare tuples that hold custom comparable values, use the GreaterThan3C function.
 func GreaterThan3[Ty1, Ty2, Ty3 constraints.Ordered](host, guest T3[Ty1, Ty2, Ty3]) bool {
  return Compare3(host, guest).GT()
 }
 
-// GreaterThan3C returns whether the host tuple is semantically less than the guest tuple.
+// GreaterThan3C returns whether the host tuple is semantically greater than the guest tuple.
 // All tuple elements of the host and guest parameters must match the Comparable constraint.
 // To compare tuples that hold built-in "Ordered" values, use the GreaterThan3 function.
 func GreaterThan3C[Ty1 Comparable[Ty1], Ty2 Comparable[Ty2], Ty3 Comparable[Ty3]](host, guest T3[Ty1, Ty2, Ty3]) bool {
  return Compare3C(host, guest).GT()
 }
 
-// GreaterOrEqual3 returns whether the host tuple is semantically less than the guest tuple.
+// GreaterOrEqual3 returns whether the host tuple is semantically greater than or equal to the guest tuple.
 // All tuple elements of the host and guest parameters must match the "Ordered" constraint.
 // To compare tuples that hold custom comparable values, use the GreaterOrEqual3C function.
 func GreaterOrEqual3[Ty1, Ty2, Ty3 constraints.Ordered](host, guest T3[Ty1, Ty2, Ty3]) bool {
  return Compare3(host, guest).GE()
 }
 
-// GreaterOrEqual3C returns whether the host tuple is semantically less than the guest tuple.
+// GreaterOrEqual3C returns whether the host tuple is semantically greater than or equal to the guest tuple.
 // All tuple elements of the host and guest parameters must match the Comparable constraint.
 // To compare tuples that hold built-in "Ordered" values, use the GreaterOrEqual3 function.
 func GreaterOrEqual3C[Ty1 Comparable[Ty1], Ty2 Comparable[Ty2], Ty3 Comparable[Ty3]](host, guest T3[Ty1, Ty2, Ty3]) bool {

tuple4.go

@@ -201,42 +201,42 @@ func LessThan4C[Ty1 Comparable[Ty1], Ty2 Comparable[Ty2], Ty3 Comparable[Ty3], T
  return Compare4C(host, guest).LT()
 }
 
-// LessOrEqual4 returns whether the host tuple is semantically less than the guest tuple.
+// LessOrEqual4 returns whether the host tuple is semantically less than or equal to the guest tuple.
 // All tuple elements of the host and guest parameters must match the "Ordered" constraint.
 // To compare tuples that hold custom comparable values, use the LessOrEqual4C function.
 func LessOrEqual4[Ty1, Ty2, Ty3, Ty4 constraints.Ordered](host, guest T4[Ty1, Ty2, Ty3, Ty4]) bool {
  return Compare4(host, guest).LE()
 }
 
-// LessOrEqual4C returns whether the host tuple is semantically less than the guest tuple.
+// LessOrEqual4C returns whether the host tuple is semantically less than or equal to the guest tuple.
 // All tuple elements of the host and guest parameters must match the Comparable constraint.
 // To compare tuples that hold built-in "Ordered" values, use the LessOrEqual4 function.
 func LessOrEqual4C[Ty1 Comparable[Ty1], Ty2 Comparable[Ty2], Ty3 Comparable[Ty3], Ty4 Comparable[Ty4]](host, guest T4[Ty1, Ty2, Ty3, Ty4]) bool {
  return Compare4C(host, guest).LE()
 }
 
-// GreaterThan4 returns whether the host tuple is semantically less than the guest tuple.
+// GreaterThan4 returns whether the host tuple is semantically greater than the guest tuple.
 // All tuple elements of the host and guest parameters must match the "Ordered" constraint.
 // To compare tuples that hold custom comparable values, use the GreaterThan4C function.
 func GreaterThan4[Ty1, Ty2, Ty3, Ty4 constraints.Ordered](host, guest T4[Ty1, Ty2, Ty3, Ty4]) bool {
  return Compare4(host, guest).GT()
 }
 
-// GreaterThan4C returns whether the host tuple is semantically less than the guest tuple.
+// GreaterThan4C returns whether the host tuple is semantically greater than the guest tuple.
 // All tuple elements of the host and guest parameters must match the Comparable constraint.
 // To compare tuples that hold built-in "Ordered" values, use the GreaterThan4 function.
 func GreaterThan4C[Ty1 Comparable[Ty1], Ty2 Comparable[Ty2], Ty3 Comparable[Ty3], Ty4 Comparable[Ty4]](host, guest T4[Ty1, Ty2, Ty3, Ty4]) bool {
  return Compare4C(host, guest).GT()
 }
 
-// GreaterOrEqual4 returns whether the host tuple is semantically less than the guest tuple.
+// GreaterOrEqual4 returns whether the host tuple is semantically greater than or equal to the guest tuple.
 // All tuple elements of the host and guest parameters must match the "Ordered" constraint.
 // To compare tuples that hold custom comparable values, use the GreaterOrEqual4C function.
 func GreaterOrEqual4[Ty1, Ty2, Ty3, Ty4 constraints.Ordered](host, guest T4[Ty1, Ty2, Ty3, Ty4]) bool {
  return Compare4(host, guest).GE()
 }
 
-// GreaterOrEqual4C returns whether the host tuple is semantically less than the guest tuple.
+// GreaterOrEqual4C returns whether the host tuple is semantically greater than or equal to the guest tuple.
 // All tuple elements of the host and guest parameters must match the Comparable constraint.
 // To compare tuples that hold built-in "Ordered" values, use the GreaterOrEqual4 function.
 func GreaterOrEqual4C[Ty1 Comparable[Ty1], Ty2 Comparable[Ty2], Ty3 Comparable[Ty3], Ty4 Comparable[Ty4]](host, guest T4[Ty1, Ty2, Ty3, Ty4]) bool {