Update docs

Author: freeformz

locked.go

@@ -5,8 +5,8 @@ import (
 	"sync"
 )
 
-// LockedMap is a set implementation using a map and a read-write mutex. Instances of this type are safe to be used
-// concurrently. Iteration holds the read lock for the duration of the iteration.
+// LockedMap is a set implementation using a map and a mutex (via the sync.Cond). Instances of this type are safe to be used
+// concurrently. Iteration holds the lock for the duration of the iteration.
 type LockedMap[M comparable] struct {
 	*sync.Cond
 	iterating bool
@@ -98,6 +98,8 @@ func (s *LockedMap[M]) Cardinality() int {
 	return len(s.m)
 }
 
+// Iterator yields all elements in the set. It holds a lock for the duration of iteration, so calling other methods will block
+// until iteration is complete.
 func (s *LockedMap[M]) Iterator(yield func(M) bool) {
 	s.Cond.L.Lock()
 	s.iterating = true

locked_ordered.go

@@ -103,6 +103,8 @@ func (s *LockedOrdered[M]) Cardinality() int {
 	return len(s.values)
 }
 
+// Iterator yields all elements in the set in order. It holds a lock for the duration of iteration, so calling other methods will block
+// until iteration is complete.
 func (s *LockedOrdered[M]) Iterator(yield func(M) bool) {
 	s.Cond.L.Lock()
 	s.iterating = true

mapset.go

@@ -55,6 +55,7 @@ func (s Map[M]) Cardinality() int {
 	return len(s)
 }
 
+// Iterator yields all elements in the set.
 func (s Map[M]) Iterator(yield func(M) bool) {
 	for k := range s {
 		if !yield(k) {

ordered.go

@@ -68,6 +68,7 @@ func (s *Ordered[M]) Cardinality() int {
 	return len(s.values)
 }
 
+// Iterator yields all elements in the set in order.
 func (s *Ordered[M]) Iterator(yield func(M) bool) {
 	for _, k := range s.values {
 		if !yield(k) {

set.go

@@ -9,9 +9,8 @@ import (
 	"slices"
 )
 
-// Set is a collection of unique elements. The elements must be comparable.
-// Each set implementation must implement this interface as the set functions within this package
-// build on top of this interface.
+// Set is a collection of unique elements. The elements must be comparable. Each set implementation must implement this
+// interface as the set functions within this package build on top of this interface.
 type Set[M comparable] interface {
 	// Add an element to the set. Returns true if the element was not already in the set.
 	Add(M) bool
@@ -28,9 +27,10 @@ type Set[M comparable] interface {
 	// Contains returns true if the set contains the element.
 	Contains(M) bool
 
-	// Iterator for the set. The yield function is called for each element in the set.
-	// If yield function returns false, the iteration is stopped. The order of iteration
-	// is not guaranteed. Changing the set while iterating over it is undefined behavior.
+	// Iterator for the set elements. The yield function is called for each element in the set. If the yield function
+	// returns false, the iteration is stopped. The order of iteration is not guaranteed unless the set is ordered.
+	// Changing the set while iterating over it is undefined. It may or may not be safe to change the set or allowed
+	// based on the implementation in use. Implementations must document their iteration safety.
 	Iterator(yield func(M) bool)
 
 	// Remove an element from the set. Returns true if the element was in the set.

sync.go

@@ -63,6 +63,8 @@ func (s *SyncMap[M]) Cardinality() int {
 	return n
 }
 
+// Iterator yields all elements in the set. It is safe to call concurrently with other methods, but the order and
+// behavior is undefined, as per [sync.Map]'s `Range`.
 func (s *SyncMap[M]) Iterator(yield func(M) bool) {
 	s.m.Range(func(key, _ interface{}) bool {
 		return yield(key.(M))