containers: Ordered: Add doc comments.

1 files changed, 23 insertions, 0 deletions

diff --git a/lib/containers/ordered.go b/lib/containers/ordered.go
index aa2c94d..1ebc17e 100644
--- a/lib/containers/ordered.go
+++ b/lib/containers/ordered.go
@@ -12,12 +12,34 @@ type _Ordered[T any] interface {
 	Compare(T) int
 }
 
+// An Ordered[T] is a type that has a
+//
+//	func (a T) Compare(b T) int
+//
+// method that returns a value <1 if a is "less than" b, >1 if a is
+// "greater than" b, or 0 if a is "equal to" b.
+//
+// You can conceptualize as subtraction:
+//
+//	func (a T) Compare(b T) int {
+//		return a - b
+//	}
+//
+// Be careful to avoid integer overflow if actually implementing it as
+// subtraction.
 type Ordered[T _Ordered[T]] _Ordered[T]
 
+// NativeOrdered takes a type that is natively-ordered (integer types,
+// float types, and string types), and wraps them such that they
+// implement the Ordered interface.
 type NativeOrdered[T constraints.Ordered] struct {
 	Val T
 }
 
+// NativeCompare[T] implements the Ordered[T] Compare operation for
+// natively-ordered (integer types, float types, and string types).
+// While this operation be conceptualized as subtration,
+// NativeCompare[T] is careful to avoid integer overflow.
 func NativeCompare[T constraints.Ordered](a, b T) int {
 	switch {
 	case a < b:
@@ -29,6 +51,7 @@ func NativeCompare[T constraints.Ordered](a, b T) int {
 	}
 }
 
+// Compare implements Ordered[T].
 func (a NativeOrdered[T]) Compare(b NativeOrdered[T]) int {
 	return NativeCompare(a.Val, b.Val)
 }