Don't use the word 'unwrap' to describe core 'unwrap' functions

[brson]

It's tautological, and "unwrap" is essentially Rust-specific jargon.

I was teaching a newbie some Rust, and doing the usual hand-waving about error handling using unwrap. They asked what 'unwrap' means. I said look it up in the docs. The docs read (paraphrased) "unwrap unwraps". I was embarrassed.

This patch just changes the language to "consume", which is at least more general than "unwrap", has a clear English-language meaning, and is not the same word as the function names. It has the downside that "consuming" in the type system is still pretty Rust-specific and may not have obvious meaning in this context.

[rust-highfive]

r? @rkruppe

(rust_highfive has picked a reviewer for you, use r? to override)

[brson]

Oh, note that the "main" Option::unwrap function says "Move the value ... ", so it already has better docs, but Result::unwrap uses the "unwrap" language. It could be nicer to mimic that functions docs for all the other unwraps.

[brson]

OK, I'm taking another pass at this to try to make all the unwrap docs more consistent.

[brson]

I pushed another commit that tries to make the various unwrap methods across Option and Result consistent in their language. It uses the "Move" language from the existing Option::unwrap docs, though I think it reads a bit awkwardly.

I also changed two argument names in the Result methods, optb -> default, f -> op, for consistency with Option.

I didn't touch the unwrap_or_default docs.

[brson]

OK, realizing their are various non-unwrap methods that also use the "unwrap" language, I'm feeling a bit frustrated and indecisive. I think none of them should say "unwrap" (unless they are explicitly referencing the unwrap method) since a newbie could encounter any of them and have no idea what unwrap means.

But I also think the "Moves the value v out of the Option<T> ..." language is verbose and doesn't read great.

I'm going to close this and rethink the whole thing. BBL...

[Ixrec]

FWIW, "unwrap" also has a regular English meaning separate from its jargon meaning, i.e. to remove a wrapper / layer of wrapping around the thing you're really interested in. The idea is that types like Box<T>, Option<T>, Result<T, E> are often just wrapping a T. The similar word "unbox" also comes to mind, but that's more easily mistaken for a Box-specific operation (std::num::Wrapping exists, but is far less common). I've also heard this usage of "unwrapping" in the context of several other languages to talk about smart pointers, monadic wrapper types, Java's autoboxing/autounboxing, or even just user-defined structs with one field, so IMO it's not even "Rust jargon"; at worst it's programming jargon. And finally, at least to my ear, the gap between "consume"'s English meaning and Rust meaning is significantly wider than it is for "unwrap."

But I do agree that there are some "unwrap() unwraps" traps worth fixing here. When someone is looking at the docs specifically for method foo(), it's reasonable to address the possibility that they have no idea what the English word foo means.

[mati865]

I think extract would fit here as well and it doesn't collide with other names.