option to enforce ordering for attributes and doc comments

[yaahc]

There are two orderings possible with items that have both attributes and doc comments

/// doc comment
#[attribute]
fn foo() {}

#[attribute]
/// doc comment
fn foo() {}

A random twitter poll that I cannot find anymore made it clear that option 1 is significantly more popular than option 2 and some people (myself included) would prefer if we just settled on one of these variants and consistently enforced that style.

The proposed feature is to add a check for items that have both a doc comment and attributes and to format them all consistently. There should be an option to select either style. I believe that the former should be the default setting.

[topecongiro]

cc #3303.

[yaymukund]

I started on this. I've got something mostly working, but want to doublecheck the expected behavior when doc comments are separated by comments, attributes, or other such. Here's what I was thinking:

Example 1

https://github.com/rust-lang/rustfmt/blob/1eb8764e4043d80ad75f8bbb59ba3e6ce2d95975/tests/target/attrib.rs#L53-L61 Becomes:

    /// Blah blah bing.
    /// Blah blah bing.
    /// Blah blah bing.

    #[attrib1]
    #[attrib2]
    // Another comment that needs rewrite because it's tooooooooooooooooooooooooooooooo
    // loooooooooooong.
    fn f4(self) -> Cat {}

Example 2

https://github.com/rust-lang/rustfmt/blob/1eb8764e4043d80ad75f8bbb59ba3e6ce2d95975/tests/target/attrib.rs#L1-L17 Becomes:

// rustfmt-wrap_comments: true
// Test attributes and doc comments are preserved.
//! Doc comment
//! Crate doc comment
#![doc(
    html_logo_url = "https://www.rust-lang.org/logos/rust-logo-128x128-blk-v2.png",
    html_favicon_url = "https://doc.rust-lang.org/favicon.ico",
    html_root_url = "https://doc.rust-lang.org/nightly/",
    html_playground_url = "https://play.rust-lang.org/",
    test(attr(deny(warnings)))
)]
#![attribute]
// Comment

[ayazhafiz]

That seems reasonable to me, at least on a first pass.

[calebcartwright]

Thanks for digging into this @yaymukund! We'll need someone to open an RFC in the Style Guide repo to get direction on what the default should be. Would you be interested in submitting that?

[spanishpear]

@calebcartwright given https://github.com/rust-lang/style-team/issues/156 was closed, does that subsequently mean this issue is no longer planned?

For context, I was hoping to enable a rule for a similar ordering enforcement in our own codebases, and found the chain of issues, ending up here! I would love to have a rule for this, but I understand the rationale surrounding potential side-effects with proc-macros.

Alternatively, I wonder if clippy would be open to a suspicious rule for this 🤔

Thanks!

[axelkar]

I second making this a Clippy lint, due to the potential proc-macro issues. Or maybe this could be added with a configuration option, like wrap_comments.