Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

prevent unnecessary indent when formatting doc comment code snippets #5636

Open
wants to merge 1 commit into
base: master
Choose a base branch
from

Conversation

ytmimi
Copy link
Contributor

@ytmimi ytmimi commented Dec 22, 2022

Fixes #5623

When formatting code snippets in doc comments, we start by wrapping the content of the code block in an fn main(){} and add indentation. We do this because we're about to create an internal rustfmt Session that will try to parse the input snippet as a crate. In order for that operation to succeed the snippet can only contain top level items like function definitions.

To illustrate the transformation, assume we're starting with the following doc comment:

//! ```rust
//! let x =       "hello world!";
//! ```

After the transformation rustfmt will actually try to format this:

fn main() {
    let x =       "hello world!";
}

It turns out that during the transformation described above, we sometimes add indentation to empty lines. This normally isn't an issue because rustfmt removes the redundant indentation while reformatting, but in the event a user adds an inner #![rustfmt::skip] attribute to their doc comment snippet the inner attribute will be applied to the fn main(){} and we'll leave the erroneous indentation in place.

So this is what rustfmt will try to reformat:

fn main() {
    #![rustfmt::skip]
    // ... the rest of the doc comment snippet
}

To prevent this issue entirely we won't add indentation to any line that is empty or only contains whitespace.

r? @calebcartwright

@calebcartwright
Copy link
Member

This is intriguing, and I suspect, may potentially address a bevy of other issues (at least partially). I'd like to see the idempotence check with this branch as well because it is the type of change that has a potentially large blast radius. I'd also be curious to see if/how this impacts other reported bugs/issues.

Fixes 5623

When formatting code snippets in doc comments, we start by wrapping the
content of the code block in an `fn main(){}` and add indentation. We do
this because we're about to create an internal rustfmt `Session` that
will try to parse the input snippet as a crate. In order for that
operation to succeed the snippet can only contain top level items like
function definitions.

To illustrate the transformation, assume we're starting with the following
doc comment:

```rust
//! ```rust
//! let x =       "hello world!";
//! ```
```

After the transformation rustfmt will actually try to format this:

```rust
fn main() {
    let x =       "hello world!";
}
```

It turns out that during the transformation described above, we sometimes
add indentation to empty lines. This normally isn't an issue because
rustfmt removes the redundant indentation while reformatting, but in the
event a user adds an inner `#![rustfmt::skip]` attribute to their doc
comment snippet the inner attribute will be applied to the `fn main(){}`
and we'll leave the erroneous indentation in place.

So this is what rustfmt will try to reformat:

```rust
fn main() {
    #![rustfmt::skip]
    // ... the rest of the doc comment snippet
}
```

To prevent this issue entirely we won't add indentation to any line
that is empty or only contains whitespace.
@ytmimi
Copy link
Contributor Author

ytmimi commented Jan 29, 2024

Just getting back around to this now as I'm going through the backlog. I kicked off the Diff-Check.

Edit: The job ran without any errors ✅

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

Successfully merging this pull request may close these issues.

Trying to skip formatting in doc comments
2 participants