Unneeded rust as language in rustdoc's documentation examples

[ojeda]

What it does

In a documentation example, when processed by rustdoc, it is strictly equivalent to write rust or not (https://doc.rust-lang.org/rustdoc/write-documentation/documentation-tests.html).

Thus it would be nice to have a lint that suggest the removal of the unneeded rust as language for the example.

Some projects may prefer the opposite, i.e. always writing rust, thus the equivalent lint for that may be a good idea as well. Either way, consistency is typically an improvement.

Advantage

• Less busy, and more consistent, source code.
• When contributing to a project, there is no need to remember if it is supposed to be written or not.

Drawbacks

• It may be slightly harder to copy the code into a non-rustdoc system.

Example

/// ```rust
/// let x = 5;
/// ```

Could be written as:

/// ```
/// let x = 5;
/// ```

[GnomedDev]

Should this be a part of clippy? This seems like a better fit for a rustdoc warning, as it has all the markdown parsing code already.

[ojeda]

Yeah, that may be right, I wasn't sure where to place it (there are other doc-related lints in Clippy already and perhaps rustdoc treats "stylistic diagnostics" like rustc, i.e. leaves those up to Clippy and other tools).

Cc @GuillaumeGomez

[GuillaumeGomez]

I think it's actually a better idea to put it into clippy as a style lint because it's completely ok to add rust marker on a codeblock, even if useless in most cases.

[notriddle]

If someone uses #![doc=include_str!("../README.md")], then they'll need the rust tag to make it render right in anything other than rustdoc.

[GuillaumeGomez]

Good point: we should ignore doc included with include_str!.