typedsync: Bring up to being a mostly-drop-in replacement for Go 1.20 sync

1 files changed, 17 insertions, 4 deletions

diff --git a/typedsync/map.go b/typedsync/map.go
index 6bb1170..2f94ae2 100644
--- a/typedsync/map.go
+++ b/typedsync/map.go
@@ -10,20 +10,33 @@ import (
 
 // Map is a type-safe equivalent of the standard library's sync.Map.
 //
-// With versions of Go prior to Go 1.20, Map is specified too loosely,
-// as
+// See the [sync.Map documentation] for full details.
+//
+// Go 1.20 added sync.Map.Swap method; this method is only available
+// on typedsync.Map if built with Go 1.20 or later.
+//
+// Go 1.20 added sync.Map.CompareAndDelete and sync.Map.CompareAndSwap
+// methods that are only usable if V is a comparable type; these
+// methods are not available on typedsync.Map, but when typedsync is
+// built with Go 1.20 or later they are available on a separate
+// ComparableMap type.
+//
+// When typedsync is built versions of Go prior to Go 1.20,
+// typedsync.Map is specified too loosely, as
 //
 //	Map[K any, V any]
 //
-// while with Go 1.20 and later, Map is specified as
+// while with Go 1.20 and later, typedsync.Map is specified as
 //
 //	Map[K comparable, V any]
 //
 // This is because with Go versions prior to 1.20, 'comparable' was
 // overly strict, disallowing many types that are valid map-keys (see
 // https://github.com/golang/go/issues/56548).  The type used as K in
-// a Map older versions of Go must be a valid map-key type, even
+// a Map with older versions of Go must be a valid map-key type, even
 // though the type specification of Map does not enforce that.
+//
+// [sync.Map documentation]: https://pkg.go.dev/sync#Map
 type Map[K mapkey, V any] struct {
 	inner sync.Map
 }