Document what merging a row of repeated header labels looks like (#120)

[mstackhouse]

The only clinify change to come out of #120. The investigation is written up in full on the issue; the short version is that 7 of the 9 reported tables were a harness bug and the other 2 were pilot code, so there is no rendering fix to make here.

What there is: the merge docs explained the mechanism — identical, adjacent header cells are merged — but never the symptom. Merged, the run renders as one label centred over all of it, so the repeats are no longer there to read.

That matters most for the bottom header row, which holds each column's own label. In the case that prompted this, six columns each labelled "Baseline" came out as a single Baseline spanning all six:

ref   Week@267 Shift@303 to@326 Baseline@352 Baseline@413 Baseline@473 Baseline@534 Baseline@594 Baseline@655
cand  Week@269 to@314 Baseline@499

Five labels gone from the output, with nothing to say so. merge = "spanners" is the answer and was already there — only the description of what it saves you from was missing.

Considered and rejected

Changing the merge default from TRUE to "spanners". There is a real argument for it: the bottom row holds each column's own label, so merging it hides labels rather than forming a spanner, which is exactly where merging is most likely to be unintended, and it produced the worst symptom of anything found in #120.

Against: it is a breaking default change on a CRAN package that would silently alter existing users' output and every snapshot test, to fix something with a documented one-word opt-out that the very suite that hit this already uses on a neighbouring table. Not worth the cost. Recording it here in case it belongs in a future major version.

Verification

Documentation only — no code paths touched. Full suite run anyway: 2,176 tests pass, no snapshot changes. DESCRIPTION is deliberately untouched; the local roxygen2 is 8.0.0 against the repo's pinned 7.3.2, and document() wants to rewrite RoxygenNote into Config/roxygen2/version. That bump is not this PR's business, so it was reverted — the regenerated .Rd carries only the prose change.

🤖 Generated with Claude Code