| name | doc-sync |
| description | Syncs README.md, sml/README.md, and top-level package doc.go comments against the current exported API. Only corrects verifiable drift (wrong signatures, renamed options, missing/removed symbols, stale behavior). Does not rewrite prose for style. |
doc-sync
Goal: docs reflect current source. Correct factual drift. Do not restructure or restyle.
Default scope: README.md, sml/README.md, and doc.go of each public package listed in 100-overview.md. Narrow with an argument. docs/secs1/*.md design notes are read-only history — flag only if they misrepresent current behavior.
Procedure
- Inventory source. For each package in scope, list exported symbols, functional options, and the package-level comment. Do not derive public-API facts from
internal/.
- Inventory docs. Extract every code block, signature, option name, shortcut constructor (
A, I4, L, …), and SEMI-standard reference in the scoped files.
- Diff. For each mismatch, classify:
- stale — exists but described differently (wrong signature, option, default, behavior).
- missing — source symbol / option / error / behavior not mentioned.
- phantom — doc describes something that no longer exists.
- Fix. Targeted edits only. Match signatures verbatim (parameter names, types, variadic). Correct option names everywhere. For phantom symbols, delete the section (and add a one-line "renamed to X" where a replacement exists). For missing symbols, add a stub entry per
400-documentation.md.
- Don't fix when it requires author intent (ambiguous grammar, design-note decisions, multiple plausible rewordings) — flag as "needs attention."
Rules
- Read the source file before editing a doc claim.
- Verify SML snippets parse under the current parser mode (strict / non-strict).
- Don't touch prose tone, section order, or design notes.
- Don't fabricate API behavior. If source is ambiguous, quote both the claim and the source.
Report
## doc-sync report
### Applied
- README.md: corrected SendDataMessage signature; added WithValidateDataMessage to the secs1 example.
- hsmsss/doc.go: documented exponential-backoff reconnect; added WithLinktestFailureThreshold.
### Needs attention
- README.md L300: SML round-trip example ambiguous between strict / non-strict — author input needed.
### No changes
- gem/doc.go, logger/doc.go
