New lint suggestion: doctest doesn't use documented item

What it does

It happened to me a few times that I was copy-pasting a method to make some light changes. I then renamed the method in the pasted code, but forget to change the name in the doctest. I then had a duplicated doctest on an unrelated method.

Similarly, i think the lint should fire if a doctest on a struct S doesn't use S, and on a module m if it doesn't use m.

Lint Name

not sure maybe suspicious_doctest or doctest_doesnt_test

Category

suspicious

Advantage

• It is confusing when a doctest on S::dec doesn't use S::dec. When the test fails you would look inside dec for the bug, which costs time.
• When there is a doctest on S::dec, you assume S::dec is tested. (This could be solved with code coverage).
• When a doctest on S::dec doesn't use S::dec, you should be considering if the test really belongs there. Maybe the module docs would be a better place?

Drawbacks

There could be valid usecases, but at the moment I can't think of any.

I searched through the docs of Vec and Command and couldn't find anything that would violate this proposed lint.

Example

struct S(i8);
impl S {
    /// Increases the contained value
    /// ```
    /// let mut s = S(0);
    /// s.inc();
    /// assert_eq!(s.0, 1);
    /// ```
    fn inc(&mut self) { self.0 += 1; }

    /// Decreases the contained value
    /// ```                                                // Lint should fire here because the test doesn't reference `dec`
    /// let mut s = S(0);
    /// s.inc();                                     
    /// assert_eq!(s.0, 1);
    /// ```
    fn dec(&mut self) { self.0 -= 1; }
}

No files, tests, or entry points are named; start by reading the proposed Rust example and defining how doctests are associated with methods, structs, and modules. Done means the lint reliably reports doctests that do not use their documented item, with appropriate handling for valid use cases.