You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
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.
Hi, I am interested in helping with this godoc/documentation issue if outside contributors are welcome.
I am a software engineer and technical writer. I can help update method docs and package-level guidance so the memory-model, Len hot-loop warning, Keys/Values non-correlation, Range panic behavior, and zero-vs-missing distinction are clear with examples.
Activity
BboyGT commentedon Jun 27, 2026
Hi, I am interested in helping with this godoc/documentation issue if outside contributors are welcome.
I am a software engineer and technical writer. I can help update method docs and package-level guidance so the memory-model, Len hot-loop warning, Keys/Values non-correlation, Range panic behavior, and zero-vs-missing distinction are clear with examples.
GitHub: https://github.com/BboyGT
X: https://x.com/GodstimeDev
Email: masathygolden@gmail.com
If useful, I can propose a small doc-only PR for review.