rust-lang / rust-lang/rust-clippy
Lint method doc comments which contain no examples that call the method
Nobody has claimed this yet.
- Dominant language
- Rust
- Stars
- 13.5k
- Forks
- 2.2k
- Avg merge
- 2d 10h
- Merged PRs (30d)
- 32
Description
Sort of long explanation for a simple thing: it's very common in Rust to provide code examples in doc comments to explain how a method is used. However, sometimes methods are the same, and we accidentally copy-paste a doc comment which does not actually call the method it's documenting. This should warn by default, because it's probably a mistake.
I don't think that this warning should warn for doc comments which don't contain code examples, just specifically ones that don't call the thing they're documenting. The former would be better for rustfmt, whereas the latter is something that would be good for a linter like clippy.
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 the issue description and inspect Clippy's existing documentation-related lints and their tests. Determine how examples are parsed and how a method call is identified. Done means a default warning is emitted only when a doc comment contains examples that do not call the documented method, while comments without examples remain unaffected.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- rust
- Domain
- tooling
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100