RFC: Statically enforce that only one type of doc comment is present on any given item

[bstrie]

This is an abomination, yet totally legal:

/**
 * foo
 */

/// bar

#[doc="spam"]
mod m {
  #[doc="eggs"];

  //! baz

  /*! qux */
}

fn main() {}

Putting aside the fact that we just have waay too many forms of doc comments, this should be a compile-time error. I can think of no scenario where you'd want to split an item's documentation up among several comments, let alone several different types of comments.

[novabyte]

Agreed. For what it's worth my favorite comment form for Rust code is:

#[doc="""
My documentation is great. :)
"""]
mod m {
}

[bstrie]

See also #6782, in the case where we decide to have more than one type of doc comment form.

[ben0x539]

I can think of no scenario where you'd want to split an item's documentation up among several comments, [...]

I tend to agree, but note that right now multiple lines of /// comments end up as separate attributes in the ast. So that'd need to change to ban multiple doc comments (unless we remove the //////! forms).

[bstrie]

See also PR #6757.

[emberian]

I agree that this should be deny-linted by default.

[huonw]

Triage: no change.

[flaper87]

This needs to go through the new RFC process. https://github.com/rust-lang/rfcs/