rust-lang / rust-lang/rustfmt

Trailing blank line removal in doc comments is not idempotent

Open
#6,168 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

A-doc-comments A-whitespace C-bug I-non-idempotency only-with-option UO-format_code_in_doc_comments UO-normalize_comments UO-wrap_comments
Dominant language
Rust
Stars
7k
Forks
1.1k
Avg merge
2d 13h
Merged PRs (30d)
24

Description

Description

Only one trailing, blank line in a comment is removed each time rustfmt is run, so formatting is not idempotent if multiple trailing, blank lines are present. Blank line removal is enabled by any of the normalize_comments, wrap_comments, or format_code_in_doc_comments (for doc comments only) configuration options. All these features are unstable, so this affects nightly only (as of 2024-05-21 / d5f1200ed6a8e375f963e0c59a8bee45c0018c55)

This issue is fixed by PR #6163.

Reproduction

Given

rustfmt.toml

wrap_comments = true

code.rs

//! I am a humble module doc comment with many trailing lines
//!
//!

Run

# rustfmt code.rs

Expected

code.rs

//! I am a humble module doc comment with many trailing lines

Actual

code.rs

//! I am a humble module doc comment with many trailing lines
//!

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start with the reproduction in rustfmt.toml and code.rs, using wrap_comments = true and running rustfmt on the module doc comment. Compare the result with the expected output and inspect PR #6163 for the existing fix; done means repeated formatting leaves no trailing blank comment lines and remains unchanged on the next run.

Written by the indexing model from the issue text.

Assessment

Tech stack
rust
Domain
tooling
Issue type
Bug
Difficulty
2/5
Estimated time
1-3 hours
Activity status
Stale
Clarity
Clearly specified
Newbie friendliness
20/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.