Enforce ordering for doc comments

[yaymukund]

Currently, we do not enforce ordering of doc comments. This RFC proposes a new option:

reorder_doc_comments

Reorder doc comments to be above or below attributes and regular comments.

• Default value: "Prepend"
• Possible values: "Prepend", "Append", "Off"

"Prepend" (default)

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

"Append"

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

Advantages

• Easy to scan.
• Grouping doc comments more accurately reflects how they will be ultimately rendered.

Concerns

• This could break proc macros that rely on processing doc attributes in a particular order with respect to other attributes.

Details

1. In the case where there are multiple doc comments, each on their own lines, they would be grouped.

   /// doc comment 1
   #[attribute_a]
   /// doc comment 2
   #[attribute_b]
   fn foo() {}
   
   // Becomes:
   
   /// doc comment 1
   /// doc comment 2
   #[attribute_a]
   #[attribute_b]
   fn foo() {}

2. This would also affect ordering relative to doc attributes:

   //! Crate doc comment
   #![doc(
   html_logo_url = "https://www.rust-lang.org/logos/rust-logo-128x128-blk-v2.png",
   )]

Related issues

• https://github.com/rust-lang/rustfmt/issues/3744 (See also how the proposed changes would impact unit tests.)
• https://github.com/rust-lang/rustfmt/issues/3303

I tried to read through the docs & follow the process, but please let me know if I missed anything 😊

[joshtriplett]

This could potentially break proc macros. Doc comments become doc attributes that proc macros can process, and thus order matters.

In most cases, this won't matter, but we can't know that.

[yaymukund]

@joshtriplett Thank you for taking a look. That makes sense. I've added it to the RFC.

[yaymukund]

I was wondering what's the right way to move this forward?

[calebcartwright]

Thanks for the suggestion, but I'm going to close. We don't want to add options that have breaking paths, especially ones like this that can be a source of subtle bugs (including ones that may not be detected until runtime).