rust-lang / rust-lang/rust-clippy
Unneeded `rust` as language in `rustdoc`'s documentation examples
Nobody has claimed this yet.
- 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-
rustdocsystem.
Example
/// ```rust
/// let x = 5;
/// ```
Could be written as:
/// ```
/// let x = 5;
/// ```
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- 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