rust-lang / rust-lang/rust-clippy

Unneeded `rust` as language in `rustdoc`'s documentation examples

Open
#13,604 5 comments 4 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

A-lint G-Rust-for-Linux
Dominant language
Rust
Stars
13.5k
Forks
2.2k
Avg merge
2d 10h
Merged PRs (30d)
32

Description

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;
/// ```

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

Start with rustdoc's documentation-tests guidance linked in the issue and compare how language tags are processed. Decide which consistency policy the lint should enforce, then verify that the lint identifies redundant rust tags without affecting other documentation examples; the issue does not name implementation files or tests.

Written by the indexing model from the issue text.

Assessment

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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.