doc: restyle docs

json/benchmarks/lexers/comparative/easyjson/walk.go

@@ -25,7 +25,7 @@ import (
 func Walk(data []byte) error { return walk(data, false) }
 
 // WalkConvertNumbers is like Walk but converts each number with Float64(), which
-// is where jlexer actually validates number grammar (Raw/JsonNumber do not). This
+// is the point where jlexer validates number grammar (Raw/JsonNumber do not). This
 // rebalances the comparison against the default-lexer, which always validates
 // numbers while lexing — though Float64 also *loses precision*, which the
 // default-lexer never does.

json/benchmarks/writers/README.md

@@ -79,7 +79,7 @@ Steady-state medians (6×, `benchstat`, AMD Ryzen 7 5800X, `io.Discard` sink):
 The benchmark writes to `io.Discard`, whose `Write` is a no-op. Flushing is therefore
 free, so `our-buffered-2MB` (one flush) performs essentially the same as the default
 `our-buffered` (many free flushes): against this sink, buffer size only changes flush
-*frequency*, which costs nothing. The large-buffer config is where the memory-for-speed
+*frequency*, which costs nothing. The large-buffer config is the point the memory-for-speed
 trade pays off against a *real* sink (file, socket, gzip), where each flush is a syscall:
 there the 4 KiB buffer pays N writes and the 2 MiB buffer pays one. To compare raw
 per-token CPU against easyjson on equal footing, both build the whole document before the

json/internal/utf8x/utf8x.go

@@ -29,7 +29,7 @@ const (
 // FirstInvalid returns the index of the first byte of the first ill-formed sequence in b, or -1 if b is valid UTF-8.
 //
 // It is the cold, error-path counterpart of [Valid]: callers use [Valid] for the verdict and only come here to report
-// *where* the input went wrong. Keeping the position search separate is what lets [Valid] stay a bulk scan (the same
+// *where* the input went wrong. Keeping the position search separate lets [Valid] stay a bulk scan (the same
 // split simdutf makes between its SIMD checker and rewind_and_validate_with_errors).
 func FirstInvalid(b []byte) int {
 	for i := 0; i < len(b); {

json/lexers/default-lexer/README.md

@@ -208,7 +208,7 @@ multi-encoding allowance, and putting the conversion inside the lexer would cost
 * the encoding is a fact of the transport (a `charset` parameter, a file convention), which the caller knows and the
   lexer can only guess at — and, as below, cannot always guess unambiguously.
 
-What the lexers do instead is **diagnose**. A document opening with a UTF-16 or UTF-32 byte order mark is rejected
+The lexers **diagnose** instead. A document opening with a UTF-16 or UTF-32 byte order mark is rejected
 with `ErrNotUTF8` rather than with a baffling `invalid JSON token` on its first byte — the document is rejected either
 way, and neither `0xFF`/`0xFE` nor a leading NUL pair can legitimately open a JSON value, so nothing valid is
 misjudged. The error names both encodings and no endianness: UTF-32LE (`FF FE 00 00`) opens with the very bytes of the

json/lexers/default-lexer/internal/input/string.go

@@ -187,7 +187,7 @@ func (in *Input) consumeStringWhole() token.T {
 	// proven valid UTF-8 with no second pass and no call; only the rest reaches the validator (see finishStringValue).
 	// Lanes at or after the stop are trimmed off so the answer is exact, matching strscan.ScanStop's.
 	var hi uint64
-	// guard is where the inline probe stops and delegates to the AVX2 scan.
+	// guard marks where the inline probe stops and delegates to the AVX2 scan.
 	// With WithoutAVX2 it is pushed past the buffer so the loop never breaks to delegate — the string is scanned
 	// entirely by the inline SWAR word loop (the pre-AVX2 baseline), no vector call at alin.
 	guard := start + guessLong

json/lexers/default-lexer/internal/strscan/scan_amd64.go

@@ -31,7 +31,7 @@ const avx2Min = 32
 // when the CPU supports it and enough bytes remain, and to SWAR otherwise.
 // The WithoutAVX2 knob is handled by the caller (it simply never delegates here), so ScanStop always tries the kernel.
 //
-// The non-ASCII result is what lets the string scanners fuse UTF-8 detection into the scan they already perform: a run
+// The non-ASCII result lets the string scanners fuse UTF-8 detection into the scan they already perform: a run
 // this reports as pure ASCII is proven valid UTF-8 with no second pass. Both implementations answer identically.
 func ScanStop(data []byte) (int, bool) {
 	if useAVX2 && len(data) >= avx2Min {

json/lexers/yaml-lexer/walk.go

@@ -410,7 +410,7 @@ func (l *YL) mergeEntries(src ast.Node) []*ast.MappingValueNode {
 // keyString returns the string form of a scalar mapping key (matching emitKey's token value),
 // used for merge de-duplication. ok is false for a non-scalar (complex) key.
 // maxKeyUnwrap bounds the resolveKey recursion. A key can legitimately stack node properties
-// ("? !!str &a foo"), but only a handful deep; the bound is what stops an alias chain that
+// ("? !!str &a foo"), but only a handful deep; the bound stops an alias chain that
 // resolves back into itself from recursing forever.
 const maxKeyUnwrap = 16
 

json/writers/default-writer/buffered_options.go

@@ -50,7 +50,7 @@ func WithUTF8Policy(policy UTF8Policy) BufferedOption {
 // bufferedOptions carries the (immutable, unexported) [Buffered] configuration.
 //
 // It holds configuration only. Runtime state such as the working-buffer redeem handle lives on
-// [buffered], not here — that separation is what lets the configuration be a plain value (no pooling,
+// [buffered], not here — that separation lets the configuration be a plain value (no pooling,
 // no finalizer for the options themselves).
 type bufferedOptions struct {
 	bufferSize int