Summary
Several load-bearing contracts are missing from the godoc that a consumer would realistically hit:
- stdlib sync.Map memory-model guarantees ("synchronizes before") transit the wrapper unchanged — not mentioned in doc.go or any method.
Len() is O(n) per call — godoc says so, but doesn't warn against calling in a hot loop (users migrating from plain map assume O(1)).
Keys() and Values() index positions are not correlated: keys[i] does not correspond to values[i]. A consumer zipping the two slices gets silently wrong mappings.
Range callback panic propagates — not caught by the wrapper.
- Zero-value V vs missing key — struct V stores the zero struct and ok=true; pointer V stores nil and ok=true; missing stores the typed zero and ok=false. The distinction is subtle and not documented with an example.
Scope
Extend godoc on the affected methods in syncmap.go and the relationship/usage sections of doc.go. Add a short example block to doc.go's Quick Start that demonstrates the zero-vs-missing distinction.
Acceptance criteria
go doc github.com/axonops/syncmap Len mentions "not for hot loops" or equivalent.
go doc ... Values warns that indexes don't correlate with Keys().
go doc ... Range states the panic propagation contract.
doc.go has a Zero-value section contrasting pointer V and struct V.
- Memory-model pointer ("synchronizes before, per sync.Map docs") on the package comment.
Source: code-reviewer + docs-writer + security-reviewer.
Summary
Several load-bearing contracts are missing from the godoc that a consumer would realistically hit:
Len()is O(n) per call — godoc says so, but doesn't warn against calling in a hot loop (users migrating from plainmapassume O(1)).Keys()andValues()index positions are not correlated:keys[i]does not correspond tovalues[i]. A consumer zipping the two slices gets silently wrong mappings.Rangecallback panic propagates — not caught by the wrapper.Scope
Extend godoc on the affected methods in
syncmap.goand the relationship/usage sections ofdoc.go. Add a short example block to doc.go's Quick Start that demonstrates the zero-vs-missing distinction.Acceptance criteria
go doc github.com/axonops/syncmap Lenmentions "not for hot loops" or equivalent.go doc ... Valueswarns that indexes don't correlate withKeys().go doc ... Rangestates the panic propagation contract.doc.gohas a Zero-value section contrasting pointer V and struct V.Source: code-reviewer + docs-writer + security-reviewer.