docs: add godoc comments to all exported functions and methods

mc/util/case.go

@@ -7,6 +7,7 @@ import (
 
 var boundaries = []rune{' ', '_', '-', '.', ',', ';', ':', '(', ')', '[', ']', '{', '}'}
 
+// CamelCase converts a string with word boundaries to CamelCase.
 func CamelCase(s string) string {
 	ret := ""
 	atWordBoundary := true
@@ -24,6 +25,7 @@ func CamelCase(s string) string {
 	return ret
 }
 
+// SnakeCase converts a CamelCase string to snake_case.
 func SnakeCase(s string) string {
 	ret := ""
 	for i, c := range s {
@@ -38,6 +40,7 @@ func SnakeCase(s string) string {
 	return ret
 }
 
+// FirstLetterLower returns the string with the first rune lowercased.
 func FirstLetterLower(s string) string {
 	return string(unicode.ToLower(rune(s[0]))) + s[1:]
 }

mc/util/math.go

@@ -2,10 +2,12 @@ package util
 
 import "math"
 
+// FloorDiv returns floor division (rounds toward negative infinity).
 func FloorDiv(a, b int32) int32 {
 	return (a - ((a%b + b) % b)) / b
 }
 
+// BpeByNum returns the minimum bits per element needed to represent x distinct values.
 func BpeByNum(x float64) uint8 {
 	return uint8(math.Ceil(math.Log2(x)))
 }

mc/util/must.go

@@ -2,6 +2,7 @@ package util
 
 import "fmt"
 
+// MustOk returns v if ok is true, otherwise panics.
 func MustOk[T any](v T, ok bool) T {
 	if !ok {
 		panic("not ok")
@@ -9,6 +10,7 @@ func MustOk[T any](v T, ok bool) T {
 	return v
 }
 
+// MustT returns v if err is nil, otherwise panics.
 func MustT[T any](v T, err error) T {
 	if err != nil {
 		panic(err)
@@ -16,12 +18,14 @@ func MustT[T any](v T, err error) T {
 	return v
 }
 
+// Must panics if err is non-nil.
 func Must(err error) {
 	if err != nil {
 		panic(err)
 	}
 }
 
+// AssertTypeError asserts that v is of type T and returns it, or returns an error.
 func AssertTypeError[T any](v any) (T, error) {
 	var zero T
 	r, ok := v.(T)
@@ -31,6 +35,7 @@ func AssertTypeError[T any](v any) (T, error) {
 	return r, nil
 }
 
+// MapGetError returns the value for key k from map m, or an error if not present.
 func MapGetError[K comparable, V any, M map[K]V](m M, k K) (V, error) {
 	v, ok := m[k]
 	if !ok {

mc/util/utils.go

@@ -6,6 +6,7 @@ import (
 	"slices"
 )
 
+// OrderedKeys returns the keys of the map sorted in ascending order.
 func OrderedKeys[Map map[K]V, K cmp.Ordered, V any](m Map) []K {
 	keysIter := maps.Keys(m)
 	keys := slices.Collect(keysIter)
@@ -13,6 +14,7 @@ func OrderedKeys[Map map[K]V, K cmp.Ordered, V any](m Map) []K {
 	return keys
 }
 
+// AssertAndConvertMapValues asserts and converts all values in a map[string]any to type T.
 func AssertAndConvertMapValues[T any, M map[K]any, K cmp.Ordered](m M) map[K]T {
 	ret := map[K]T{}
 	for k, v := range m {
@@ -21,6 +23,7 @@ func AssertAndConvertMapValues[T any, M map[K]any, K cmp.Ordered](m M) map[K]T {
 	return ret
 }
 
+// ReverseMap returns a new map with keys and values swapped.
 func ReverseMap[M map[K]V, K cmp.Ordered, V cmp.Ordered](m M) map[V]K {
 	ret := map[V]K{}
 	for k, v := range m {
@@ -29,6 +32,7 @@ func ReverseMap[M map[K]V, K cmp.Ordered, V cmp.Ordered](m M) map[V]K {
 	return ret
 }
 
+// PopFront removes and returns the first element of the slice.
 func PopFront[T any](s []T) (T, []T, bool) {
 	if len(s) == 0 {
 		var zero T
@@ -37,6 +41,7 @@ func PopFront[T any](s []T) (T, []T, bool) {
 	return s[0], s[1:], true
 }
 
+// CombineNamAndData returns a slice containing name and data.
 func CombineNamAndData(name string, data any) []any {
 	return []any{name, data}
 }