Ensure panic docs are correct

[jendrikw]

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

[llogiq]

Shouldn't that be

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

[jendrikw]

Are you talking about the heading # Examples? Yes, that is recommended as per RFC 505, but I tend to leave it off as all my doctests are examples.

[llogiq]

Yes. Our docs should follow the recommended style.

[jendrikw]

Ok, I updated the code.