Skip to content

codegen: read a comment line of only spaces or tabs as blank - #844

Open
Caezarr wants to merge 1 commit into
anthropics:mainfrom
Caezarr:fix/doc-whitespace-blank-lines
Open

Caezarr wants to merge 1 commit into
anthropics:mainfrom
Caezarr:fix/doc-whitespace-blank-lines

Conversation

@Caezarr

@Caezarr Caezarr commented Nov 20, 2026

Copy link
Copy Markdown

What

doc_lines_impl in buffa-codegen/src/comments.rs now treats a comment line made only of spaces and tabs as a blank line, the same way it already treats an empty line. A new is_blank helper is used in the three places that checked line.is_empty(): the blank-line branch inside an indented code block, its lookahead for more indented code, and the blank-line branch for prose.

Why

protoc keeps everything after //, so a // separator line with a trailing space reaches the formatter as " ". Only "" counted as blank, so:

  • inside an indented code example, the line closed the text fence and opened a second one, so one example rendered as two code blocks with a stray line between them:

    // Example:
    //
    //     foo {
    //       bar: 1
    //     }
    // ␠
    //     baz
    

    " line1\n \n line2" produced ```text, line1, ```, , ```text, line2, ```.

  • outside a block, a line of four or more spaces opened an empty code block: "Foo.\n \nBar." produced Foo., ```text, an empty code line, ```, Bar..

CommonMark (and so rustdoc) reads a line of only spaces and tabs as a blank line: it can't start an indented code block, and it doesn't end one when more indented code follows. The formatter now agrees with that.

Tests

Two colocated unit tests in comments.rs:

  • test_doc_whitespace_only_line_within_indented_block_keeps_fence_open: " ", " ", "\t" and " " between two indented lines give one fenced block.
  • test_doc_whitespace_only_line_does_not_open_indented_block: a line of six spaces between two prose lines comes out as an empty doc line.

Both fail before the change and pass after it. cargo test -p buffa-codegen --lib passes (852 tests).

The checked-in generated code doesn't change: none of the vendored .proto files has a comment line with trailing whitespace.

@github-actions

github-actions Bot commented Nov 20, 2026 •

Copy link
Copy Markdown

All contributors have signed the CLA ✍️ ✅
Posted by the CLA Assistant Lite bot.

@Caezarr
Caezarr force-pushed the fix/doc-whitespace-blank-lines branch 2 times, most recently from ac3906a to 4db076a Compare November 20, 2026 11:54
protoc keeps everything after `//`, so a `// ` line with a trailing
space reaches the doc formatter as " ". The indented-code fencing only
treated an empty line as blank, so such a line:

- inside an indented code example, closed the `text` fence and opened
  a second one for the rest of the example, leaving a stray line
  between the two blocks
- with four or more spaces, outside a block, opened an empty code block

CommonMark, and so rustdoc, reads a line of only spaces and tabs as
blank. The formatter now does the same, with the same lookahead an
empty line gets: inside a block it keeps the block open when more
indented code follows.
@Caezarr
Caezarr force-pushed the fix/doc-whitespace-blank-lines branch from 4db076a to 2541c55 Compare November 20, 2026 11:54
@Caezarr

Caezarr commented Nov 20, 2026

Copy link
Copy Markdown
Author

I have read the CLA Document and I hereby sign the CLA

github-actions Bot added a commit that referenced this pull request Nov 20, 2026

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant