render: formatCanonicalNumber's doc comment still says grouping is "stripped unconditionally" and "never accepted back on entry" — morph#574 made both false

[Yaraslaut]

Found while fixing #583. Filed rather than folded in, per AGENTS.md: it is a
stale claim about grouping, left behind by #574/#581, and has nothing to do
with the sign change #583 is about.

Verification status: reproduced by reading the code, against real output

Revision: 992b190c (current master). The contradiction is textual, so "read
the code" is the whole of it — but the behaviour the comment describes is
measured below, not assumed.

include/morph/render/locale_format.hpp, the Doxygen block on
formatCanonicalNumber:

/// The display-direction inverse of `normalizeLocaleNumber`'s
/// decimal-separator substitution, plus display-only thousands grouping
/// (grouping is never accepted back on entry — `normalizeLocaleNumber`
/// strips it unconditionally). Passing `decimalSeparator == "."` and an empty
/// @p groupSeparator is the identity transform.

Both halves of the parenthetical are now false:

1. "grouping is never accepted back on entry" — it is. A correctly placed
   group separator normalises:

   normalizeLocaleNumber("1.050,25",     dec=",", grp=".")  -> "1050.25"
   normalizeLocaleNumber("1.000.000,25", dec=",", grp=".")  -> "1000000.25"
   

   (tests/test_render_locale_format.cpp, "every well-formed locale entry still
   normalises", pins exactly this.)

2. "strips it unconditionally" — that is precisely what morph#574 stopped it
   doing, three doc paragraphs earlier in the same header, under the heading
   "Grouping is validated, not stripped (morph#574)". A misplaced separator
   is now rejected:

   normalizeLocaleNumber("1.5",     dec=",", grp=".")  -> NULLOPT
   normalizeLocaleNumber("1.2.3.4", dec=",", grp=".")  -> NULLOPT
   

git log -S "strips it unconditionally" dates the sentence to d2cb3ae1, long
before #574 — so this is a doc comment that was correct when written and was not
updated when the behaviour it describes was deliberately reversed.

docs/spec/forms/forms.md, "Locale data formatting", has the correct account
("Grouping is validated, never merely stripped."), so the spec and the header
disagree, with the header wrong. Per AGENTS.md that makes the header the thing to
change, not the spec.

Why it matters at all

It is only a comment — no behaviour depends on it. But it is the comment a reader
hits when deciding whether formatCanonicalNumber's output can be fed back
through normalizeLocaleNumber, and it tells them the round trip does not hold
when it does. The whole point of the #574 work was that the grouping contract is
the thing people get wrong.

Fix

Delete or rewrite the parenthetical, e.g. "grouping is validated on the way back
in — see normalizeLocaleNumber — so a grouped display round-trips". A one-line
documentation change with no behavioural component.

What would change the verdict

Close it when the comment no longer claims either of the two false things. Re-open
only if normalizeLocaleNumber is ever changed back to stripping grouping
unconditionally, which #574 exists to prevent.

Not verified here

Whether the same stale claim appears anywhere else in the tree. Grepped for the
exact phrase — "strips it unconditionally" occurs once, in this header — but
not for paraphrases of it.

[Yaraslaut]

Triage: valid — reproduced, and the comment is false on both counts

Re-measured on current master be64026a, i.e. after #598 landed, because #598 edited this very file and could have fixed it in passing. It did not — the comment survives at include/morph/render/locale_format.hpp:293:

/// (grouping is never accepted back on entry — `normalizeLocaleNumber`
/// strips it unconditionally).

Measured behaviour, same revision:

normalize("1.050,25", dec=",", grp=".")  legal    -> "1050.25"
normalize("1.5",      dec=",", grp=".")  illegal  -> NULLOPT
normalize("1.2.3.4",  dec=",", grp=".")  illegal  -> NULLOPT

Both halves of the sentence are wrong, and they fail in opposite directions:

• "strips it unconditionally" — if that were true, "1.5" would yield "15". It yields NULLOPT. Grouping is validated.
• "never accepted back on entry" — if that were true, "1.050,25" would be NULLOPT. It round-trips to "1050.25". Grouping is accepted.

Not invariant 5 — the spec and the behaviour already agree

docs/spec/forms/forms.md:1383 says the opposite of the comment and matches what I measured:

Grouping is validated, never merely stripped. A group separator is dropped only where a group separator can legally be: preceded by one to three digits, followed by exactly three more, and never after the decimal separator.

So this is not a spec/code disagreement needing a decision — the spec is right, the code is right, and only the doc comment is stale. That makes it a plain documentation defect: fix the comment to match, no behaviour change, no spec change.

Worth noting why it is worth fixing rather than shrugging at: "1.5" → 15 in a de-DE locale is precisely the silent ten-times-wrong value that made #574 a defect, and this comment tells the next reader the code still behaves that way. A comment that describes the bug the code was fixed for is worse than no comment.

Scope

One doc comment. It is in locale_format.hpp, which #598 just changed, so it rebases cleanly onto current master. formatCanonicalNumber's neighbouring sign paragraph (added by #598) is accurate and should be left alone.

Verification status

Reproduced by me on be64026a with the output above — measured, not inferred. The issue's own dating of the drift to d2cb3ae1 via git log -S I have not re-checked; that provenance is taken from the report.

What would change the verdict

Nothing short of the behaviour changing back, which would itself be a regression against forms.md:1383.