Ensure panic docs are correct

What it does

Functions with a heading # Panics in their documentation as described in RFC 1574 should have at least one doctest with should_panic or at least one #[test] #[should_panic] referencing it.

This lint would trigger if that is not the case.

Lint Name

panic_doc_untested

Category

pedantic, restriction

Advantage

• Ensure code is tested and works as described in the documentation.

Drawbacks

Might be noisy if the panic conditions are nontrivial.

Example

/// Retrieves a copy of the `i`-th element of `slice`.
/// # Panics
/// Panics if `i` is outside bounds.
fn get(slice: &[u8], i: usize) -> u8 {
    slice[i]
}

Could be written as:

/// Retrieves a copy of the `i`-th element of `slice`.
/// # Panics
/// Panics if `i` is outside bounds.
/// # Examples
/// ```should_panic
/// get(&[5, 6, 7], 3);
/// ```
fn get(slice: &[u8], i: usize) -> u8 {
    slice[i]
}

Start by reading RFC 1574 and the issue's panic_doc_untested proposal, including its example. Define completion as the lint detecting documented # Panics sections that lack either a should_panic doctest or a #[test] #[should_panic] reference, while avoiding noisy reports for nontrivial panic conditions.