Rust API Guideline: Function docs include panic conditions in "Panics" section

[mcarton]

Only for functions calling panic! and other known-panicky functions (eg. Option::unwrap).

As per Function docs include error, panic, and safety considerations.

[dtolnay]

I think requiring this when calling known-panicky functions is extreme. Often something is unwrapped because it is expected to never fail. That's not something you can explain to the caller. "This function panics if... the code is wrong"?

Requiring a "Panics" section if the function uses specifically panic! would be good. If it can panic, it should be documented. If it can't panic, they should have used unreachable! instead.

[clarfonthey]

Don't forget assert! and co. as well. This shouldn't include debug_assert! because those shouldn't ever panic unless the code is broken.

[dtolnay]

We also usually don't want to document panics in logic provided by the caller.

/// # Panics
///
/// This function panics if `T`'s implementation of `Display` panics.
pub fn print<T: Display>(t: T) {
    println!("{}", t.to_string());
}