rust-lang / rust-lang/rustfmt

wrap_comments sometimes introduces trailing whitespace into rustdoc

Open
#5,421 4 comments 1 reaction 0 assignees View on GitHub

Nobody has claimed this yet.

1x-backport:pending A-comments I-trailing-whitespace only-with-option UO-wrap_comments
Dominant language
Rust
Stars
7k
Forks
1.1k
Avg merge
2d 13h
Merged PRs (30d)
24

Description

This is related to (but I believe separate from) #5420

Whatever situation that rustfmt finds itself in after failing to detect a cfg_attr-declared code block, rustfmt then randomly introduces trailing whitespace (which afaik should never happen for regular code, regular comments, regular rustdoc, rustdoc tests/examples).

Input, processed with wrap_comments = true:

//! This is a rustdoc comment that goes past the default allowed width of eighty characters. rustfmt will re-wrap this comment when run with `wrap_comments`
//! enabled.
//!
//! The preceding line does not have any whitespace and is a total of three backslashes followed by a new line (`\n`). This does not change after a
//! `rustfmt` run.
//!
//! Some examples of supported mathematical operations:
#![cfg_attr(not(feature = "std"), doc = "```ignore")]
#![cfg_attr(feature = "std", doc = "```")]
//! use size::Size;
//!
//! // No trailing whitespace is introduced on the line above
//! let s1 = Size::from_mib(13) / 2;
//! assert_eq!(s1, Size::from_mib(6.5_f32));
//!
//! // Nor is any trailing whitespace introduced on the line above or the line below, even though this comment exceeds the maximum supported width
//! let s3 = Size::from_mib(12) - Size::from_mib(14.2_f64);
//! assert_eq!(s3, Size::from_kib(-2252.8));
//! ```
//!
//! In this section of the module documentation, `rustfmt` will introduce a trailing whitespace on the line above after
//! it is executed with `wrap_comments = true`.
//!
//! `rustfmt` does not introduce trailing whitespace on the line above this comment, even though it too is rewrapped from its long length.

Output:

//! This is a rustdoc comment that goes past the default allowed width of eighty
//! characters. rustfmt will re-wrap this comment when run with `wrap_comments`
//! enabled.
//!
//! The preceding line does not have any whitespace and is a total of three
//! backslashes followed by a new line (`\n`). This does not change after a
//! `rustfmt` run.
//!
//! Some examples of supported mathematical operations:
#![cfg_attr(not(feature = "std"), doc = "```ignore")]
#![cfg_attr(feature = "std", doc = "```")]
//! use size::Size;
//!
//! // No trailing whitespace is introduced on the line above
//! let s1 = Size::from_mib(13) / 2;
//! assert_eq!(s1, Size::from_mib(6.5_f32));
//!
//! // Nor is any trailing whitespace introduced on the line above or the line
//! below, even though this comment exceeds the maximum supported width let s3 =
//! Size::from_mib(12) - Size::from_mib(14.2_f64); assert_eq!(s3,
//! Size::from_kib(-2252.8)); ```
//! 
//! In this section of the module documentation, `rustfmt` will introduce a trailing whitespace on the line above after
//! it is executed with `wrap_comments = true`.
//!
//! `rustfmt` does not introduce trailing whitespace on the line above this comment, even though it too is rewrapped from its long length.

It doesn't actually show on GitHub, but the second to last instance of an empty //! line has trailing whitespace after formatting that was not there before formatting.

This is the diff between the two with their spaces replaced with an interpunct for visibility into what's happening:

1c1,2
< //!·This is a rustdoc comment that goes past the default allowed width of eighty characters. rustfmt will re-wrap this comment when run with `wrap_comments`
---
> //!·This is a rustdoc comment that goes past the default allowed width of eighty
> //!·characters. rustfmt will re-wrap this comment when run with `wrap_comments`
4c5,6
< //!·The preceding line does not have any whitespace and is a total of three backslashes followed by a new line (`\n`). This does not change after a
---
> //!·The preceding line does not have any whitespace and is a total of three
> //!·backslashes followed by a new line (`\n`). This does not change after a
16,20c18,22
< //!·// Nor is any trailing whitespace introduced on the line above or the line below, even though this comment exceeds the maximum supported width
< //!·let s3 = Size::from_mib(12) - Size::from_mib(14.2_f64);
< //!·assert_eq!(s3, Size::from_kib(-2252.8));
< //!·```
< //!
---
> //!·// Nor is any trailing whitespace introduced on the line above or the line
> //!·below, even though this comment exceeds the maximum supported width let s3 =
> //!·Size::from_mib(12) - Size::from_mib(14.2_f64); assert_eq!(s3,
> //!·Size::from_kib(-2252.8)); ```
> //!·

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

Reproduce the provided rustdoc input with rustfmt and wrap_comments = true, then trace the comment-wrapping path responsible for the trailing whitespace on the empty //! line. Add a regression test using this case and verify formatting no longer adds trailing whitespace while preserving the expected wrapping.

Written by the indexing model from the issue text.

Assessment

Tech stack
rust
Domain
tooling
Issue type
Bug
Difficulty
3/5
Estimated time
1-2 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
38/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.