ulid: add documentation and more tests

ulid/ulid.go

@@ -1,3 +1,9 @@
+// Package ulid provides thread-safe ULID (Universally Unique Lexicographically Sortable Identifier) generation.
+//
+// ULIDs are 128-bit identifiers that are lexicographically sortable and contain
+// a timestamp component. This package uses a pool-based approach with
+// cryptographically secure random seeding and monotonic ordering for optimal
+// performance in concurrent environments.
 package ulid
 
 import (
@@ -13,6 +19,9 @@ import (
 	"go.ntppool.org/common/logger"
 )
 
+// monotonicPool is a pool of monotonic ULID readers for performance optimization.
+// Each reader is initialized with a cryptographically secure random seed
+// and random increment value to ensure uniqueness across concurrent usage.
 var monotonicPool = sync.Pool{
 	New: func() any {
 		log := logger.Setup()
@@ -37,6 +46,15 @@ var monotonicPool = sync.Pool{
 	},
 }
 
+// MakeULID generates a new ULID with the specified timestamp using a pooled monotonic reader.
+// The function is thread-safe and optimized for high-concurrency environments.
+//
+// Each call retrieves a monotonic reader from the pool, generates a ULID with the
+// given timestamp, and returns it. The reader is not returned to the pool as it
+// maintains internal state for monotonic ordering.
+//
+// Returns a pointer to the generated ULID or an error if generation fails.
+// Generation should only fail under extreme circumstances (entropy exhaustion).
 func MakeULID(t time.Time) (*oklid.ULID, error) {
 	mono := monotonicPool.Get().(io.Reader)