docs: strip self-assessment from comments added since 437e6324

[Marius Volkhart (MariusVolkhart)]

Comments merged over the last 113 commits accumulated a habit of reporting on the work rather than on the code: "verified live", "load-bearing", "Regression-shaped proof that", "MUTATION TESTED". That prose tells a reviewer the author was diligent. It tells the next maintainer nothing, and it buries the facts that actually matter — which PostgreSQL versions were checked, what the server returns, why a given query shape makes a bug bite.

Every such phrase either carried a fact or it did not. Where it did, the fact stays and the self-assessment goes:

• Verified live on PostgreSQL 16, 17, and 18: concat_ws(NULL,'x','y') IS NULL → PostgreSQL 16-18: concat_ws(NULL,'x','y') is NULL
• 63-byte budget -- verified against the live server in JdbcAnalyzerTest → 63-byte budget (PostgreSQL's NAMEDATALEN - 1 limit)
• MUTATION TESTED: ... was run by hand against this test and confirmed to turn ... red ... before being reverted back to the fix. → Reverting [...] fails this test on the chainDepth=3, shadowed=true cases: the emitted expression evaluates to the shadow's LOWER(description) value instead of the real chain's UPPER(name) value.

Where the phrase carried nothing, the sentence goes.

Also removed: emphasis-caps on ordinary English words, internal ticket references (#212, #219, #223, #238, #239, #240), and two PLAN-240.md pointers to a file that has never existed in this repository.

Kept deliberately:

• Intent markers whose reason is not recoverable from the code — they guard against a future "fix".
• The per-function audit trail in NeverNullSafeLists, a maintained list backed by a live sweep.
• Full KDoc contract text on runtime's public API, which users read in their IDE.
• pgjdbc source citations, which name a specific driver method as evidence rather than asserting diligence.

Scope was comments added or modified since 437e632. Pre-range comments were left alone even where they read badly.

Comment text only — no code line added, removed, or reordered. This was proved mechanically rather than by inspection: a Kotlin-aware tokenizer stripped comments from the before and after of all 57 changed files, preserving raw strings, escaped strings, and nested block comments, and diffed the results byte-identical. No code, string literal, annotation, or test name moved.

./gradlew :generator:check :gradle-plugin:check :runtime:check passes. Golden files unchanged.

Two verification rounds each found real defects, both since fixed. The first caught six places where a fact had been deleted rather than shortened — most seriously, SqlLexer's stripComments KDoc lost the clause explaining that skipLineComment consumes the comment's own trailing newline, without which a reader concludes the append(' ') is redundant and removable, fusing d and WHERE into dWHERE. The second confirmed those fixes and caught the PLAN-240.md references.

One thing reviewers should know: the buildBatch KDoc in ImplementationBuilder.kt was flagged during this work as contradicting its code. It does not — "discarding an intermediate flush ... leaves results empty" is a hypothetical explaining why the code captures every flush, not a claim about current behavior. It is correct but ambiguous enough to be misread, and it predates this branch. Left untouched.

🤖 Generated with Claude Code

[snyk-io]

✅ Snyk checks have passed. No issues have been found so far.

Status	Scan Engine	Critical	High	Medium	Low	Total (0)
✅	Open Source Security	0	0	0	0	0 issues
✅	Licenses	0	0	0	0	0 issues

💻 Catch issues earlier using the plugins for VS Code, JetBrains IDEs, Visual Studio, and Eclipse.