Buth/docs

.github/workflows/go.yml

@@ -1,12 +1,15 @@
 name: Go
-on: [push]
+on:
+  push:
+    branches: [main]
+  pull_request:
 jobs:
   test:
     strategy:
       matrix:
         go-version:
-          - '1.24'
           - '1.25'
+          - '1.26'
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v6

README.md

@@ -1,5 +1,7 @@
 # weakmap
 
+[![Go Reference](https://pkg.go.dev/badge/github.com/acycl/weakmap.svg)](https://pkg.go.dev/github.com/acycl/weakmap)
+
 A generic cache map implementation with [weak
 pointers](https://pkg.go.dev/weak#Pointer) as described [on the Go
 blog](https://go.dev/blog/cleanups-and-weak#weak-pointers).

go.mod

@@ -1,5 +1,5 @@
 module github.com/acycl/weakmap
 
-go 1.24.0
+go 1.25.0
 
 require golang.org/x/sync v0.19.0

weakmap.go

@@ -9,12 +9,22 @@ import (
 	"weak"
 )
 
+// Map is a concurrent cache that stores values as weak pointers. Values are
+// created on demand via the New function and automatically removed from the
+// cache when they are no longer referenced elsewhere and garbage collected.
+//
+// A Map must not be copied after first use.
 type Map[K comparable, V any] struct {
+	// New creates a value for the given key. It is called when Load is invoked
+	// for a key that is not in the cache or whose cached value has been
+	// collected. If New is nil, Load always returns nil.
 	New   func(K) *V
 	cache sync.Map
 }
 
-// Load retrieves a value from the cache.
+// Load retrieves a value from the cache, creating it via New if necessary.
+// If the cached value has been garbage collected, New is called again to
+// create a fresh value. Returns nil if New is nil.
 func (m *Map[K, V]) Load(key K) *V {
 	if m.New == nil {
 		return nil