A reflowed one-line doc comment makes clippy fire `too_long_first_doc_paragraph`

[P4suta]

Reported by a session working on another repository, and reproduced here.

[style] wrap = "sentence" splits a one-line doc comment at its sentence boundary:

/// A short summary sentence. And a second sentence that makes this first paragraph considerably longer than the threshold clippy uses.

becomes

/// A short summary sentence.
/// And a second sentence that makes this first paragraph considerably longer than the threshold clippy uses.

Markdown joins consecutive lines with a space, so the rendered paragraph is byte-identical — which is the whole premise of the wrap rule.
But clippy's too_long_first_doc_paragraph stays quiet while a doc comment is physically one line and starts measuring the moment it spans two.
A change that altered no word and no rendering therefore fails a -D warnings build.
The reporting session saw seven at once from a whole-tree fix.

A doc comment that already carries an empty /// separator is unaffected, and fix --tidy preserves that separator — verified.

Why this is not obviously ours to fix

The separator clippy wants is a blank /// line, and inserting one does change the rendering: one paragraph becomes two.
"The rendered output is unchanged" is the premise the whole style axis rests on, and reflow.rs is written around it.
Volunteering a paragraph break would be the first thing this rule does that a reader would see in the output.

Against that: rustdoc treats the first paragraph as the item's summary line, so a summary that runs to two sentences is already wrong by rustdoc's own convention, and clippy is only noticing it late. Under that reading the break is a correction rather than an intrusion.

Options

1. Nothing. The repository being formatted fixes its own doc comments, which is what the reporting session did. The cost is that ocomment fix cannot be run unattended over a Rust tree with -D warnings, which is exactly where a commit hook runs it.
2. Insert the separator when the split would leave a first paragraph over some length. Fixes the build, changes the rendering, and puts a clippy threshold inside reflow.rs.
3. Insert the separator after the first sentence of every doc comment the rule rewrites, on rustdoc's convention rather than clippy's threshold. Consistent, no foreign constant, and a larger change to what the rule does.
4. Leave a doc comment's first line alone — reflow the body, never split the summary. Keeps the rendering promise, keeps the build green, and leaves the one line most likely to be over-long untouched.

4 looks closest to right, and none of them should go in without deciding what the wrap rule promises about rendering, because the answer is currently "everything".

Not urgent: the reporting repository has handled its own, and the separator round-trips.

[P4suta]

The reporting session pushed back on option 4, and it is right.

Leaving a doc comment's first line alone would except the prose the wrap rule most exists for.
scanner.rs says as much about why documentation is in scope at all: it is exempt from the length rule because it is documentation, which is exactly why the style rules should reach it — it is the prose most readers actually read, and the prose nobody has a tool for.
Carving out the first line would also hide a real defect rather than fix one: a summary line that runs to two sentences puts the second one in rustdoc's item index, and clippy is noticing that late rather than inventing it.
And it would add a "is this a doc comment, is this its first line" branch to a rule whose output is currently predictable from the bytes alone.

The other half of the pushback settles the framing.
"Rendering is unchanged" is an invariant of reflow — of moving a line break within a paragraph — not a promise that the document's paragraph structure is frozen.
The rule already has paragraphs in its vocabulary ("a blank line separates paragraphs").
Inserting a blank /// is not a reflow at all; it is an editorial judgement sitting on top of one, and the judgement is about whether a sentence belongs in the summary.

Which puts it on the other side of the line this repository just drew.
A rewrite is TIDY because a machine can settle it and verify its own output is a fixed point.
Whether a sentence is part of an item's summary is not that: it is a DECIDE, and the tool's job there is to ask rather than to answer.

So: options 2 and 3 are out, and so is 4.
What remains is 1 — do nothing — or a narrower version of it: report a first paragraph the split leaves over-long, as a finding, and apply nothing.
That costs no foreign constant if it is worded about rustdoc's summary line rather than about clippy's threshold, and it fails in the direction this tool already fails in everywhere else.

Still not urgent.
The reporting repository has handled its own, and the machine-wide hook is fail-closed: the index is rewritten, the commit stops at exit 1, and a reflow that would not survive -D warnings never reaches a commit unattended.