rust-lang / rust-lang/rustfmt

`normalize_doc_attributes` sometimes comments out code

Open
#3,988 5 comments 2 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

C-bug only-with-option
Dominant language
Rust
Stars
7k
Forks
1.1k
Avg merge
2d 13h
Merged PRs (30d)
24

Description

The simplest test case I've been able to come up with so far is this:

mod a {
    mod b {
        #[doc = "test"]fn foo() -> () { }
    }
}

with config

normalize_doc_attributes=true
max_width=10

This example gets reformatted to the following, although it does report an error because the line exceeds the maximum width.

mod a {
    mod b {
        ///testfn foo() -> (){
        }
    }
}

I'm still not sure exactly what triggers this bug, but have found a lot of variants for this example which don't trigger it. Here are a few that might be significant:

#[doc = "test"]fn foo() -> () { }
mod a {
    mod b {
        #[doc = "test"]fn foo() { }
    }
}
mod a {
    mod b {
        #[doc = "test"]
        fn foo() -> () { }
    }
}
mod a {
    mod b {
        /// test
        fn foo() -> () { }
    }
}

In these examples, removing max_width=10 fixes the issue, but I encountered this originally in a situation where rustfmt was inexplicably being run on autogenerated files in the target directory that were part of the wayland-protocol crate. I haven't figured out what was causing rustfmt to process those files in the first place, but in that case I did have max_width=80 instead.

I have no clue what's happening or how to fix it at this point, but I'm pretty sure it has to do with formatting lines that are longer than max_width combined with some unknown other requirement. I'll try to look into this more soon and see if I can figure out how to fix it.

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 nested-module example with normalize_doc_attributes=true and max_width=10, then inspect rustfmt's documentation-attribute normalization and line-width handling. Add a regression test for the reported input and verify that formatting does not merge the documentation text with the following function or comment out code.

Written by the indexing model from the issue text.

Assessment

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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.