rustfmt adds trailing whitespace on empty doc comment

[msrd0]

This happened today in a project of mine: msrd0/cargo-doc2readme@7bb7690#diff-b3a721d27023ff07c5331d85424a395ed8907cc619825e7698ef8e3b5bf2a363

lib.rs

//! blah blah
//!
//! ```toml
#![doc = r#"blahblah = "0.1.0""#]
//! ```
//!
//! | Header1  | Header2 |
//! |----------|---------|
//! | A        | B       |
#![doc = "| C | D |"]
//! | E        | F       |
//!
//! blah blah

rustfmt.toml

edition = "2021"
max_width = 90
newline_style = "Unix"
unstable_features = true
hard_tabs = true
tab_spaces = 4
match_block_trailing_comma = true
trailing_comma = "Never"
imports_granularity = "Crate"
format_code_in_doc_comments = true
format_macro_matchers = true
use_field_init_shorthand = true
use_try_shorthand = true
condense_wildcard_suffixes = true
overflow_delimited_expr = true

# https://github.com/rust-lang/rustfmt/issues/3367
spaces_around_ranges = true

The problem cannot be reproduced with the default rustfmt configuration.

$ cargo +nightly fmt -- -V
rustfmt 1.5.1-nightly (b3bc6bf 2022-11-24)

[ytmimi]

Thanks for reaching out. The only config needed to reproduce the issue is format_code_in_doc_comments=true, however this is a duplicate of #5420.

The issue is that rustfmt doesn't format doc comments //! and doc attributes #![doc] continually. So when rustfmt sees:

//! ```toml                        <--- start of a new toml code block that never gets closed.
#![doc = r#"blahblah = "0.1.0""#]  <--- single unrelated doc comment
//! ```                            <--- start of a new code block.

If you were to write your doc comment like:

//! blah blah
//!
//! ```toml
//! blahblah = "0.1.0"
//! ```
//!
//! | Header1  | Header2 |
//! |----------|---------|
//! | A        | B       |
#![doc = "| C | D |"]
//! | E        | F       |
//!
//! blah blah

You won't run into this issue.

[msrd0]

The issue is that rustfmt doesn't format doc comments //! and doc attributes #![doc] continually.

@ytmimi Why does this matter? rustfmt removes trailing whitespace inside doc comments on empty lines, both for toml and rust codeblocks, and most certainly does not add trailing whitespace where there was none.

[ytmimi]

There's likely a bug in CommentRewrite::finish, but because of the doc attribute you use between the code fences the closing code fence is treated as an opening code fence and when we call finish the code_block_buffer isn't empty, so we join each line with the comment_line_separator ("//! " including a trailing space).

[ytmimi]

As stated above, you can avoid this issue altogether by not splitting the code fences with a doc attribute.

[msrd0]

This indeed seems to be the case that an empty line follows after an "opening" code fence. This reproduces the problem:

//! ```
//!
//! blah blah

Whenever there's a non-empty line directly following the "opening" code fence, all other lines are formatted normally.

As stated above, you can avoid this issue altogether by not splitting the code fences with a doc attribute.

That's not possible in my case, as the whole point of the file is to be an input with mixed use of doc comments and attributes. While most people won't need this, sometimes this can be necessary if e.g. the doc attribute is not a string but a macro.

[ytmimi]

Out of curiosity, why does the actual file need to contain a mix of both doc comments and doc attributes? Can you share the actual code snippet?

[msrd0]

Out of curiosity, why does the actual file need to contain a mix of both doc comments and doc attributes?

The file is part of the test suite for cargo doc2readme, a tool that reads rustdoc comments and generates a readme file. When parsing with syn, doc comments and attributes are all not trimmed, but rustdoc trims them separately, so that's why I have this test to ensure it works as expected. Context: msrd0/cargo-doc2readme#51

Can you share the actual code snippet?

The code I shared in this issue is the entire file: https://github.com/msrd0/cargo-doc2readme/blob/main/tests/pass/mixing-comments-and-attrs/lib.rs

[ytmimi]

I was incorrect earlier, this is actually a duplicate of #5421, and not #5420. They're both similar, but #5421 only focuses on the trailing whitespace issues. Luckily PR #5288 will resolve this issue once its merged.