New lint suggestion: doctest doesn't use documented item

[jendrikw]

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; }
}