Documentation on `Result::map_or_else` uses very unfortunate wording

[orlp]

The type signature of Result::map_or_else:

pub fn map_or_else<U, D, F>(self, default: D, f: F) -> U where
    F: FnOnce(T) -> U,
    D: FnOnce(E) -> U, 

Note how default is the function that gets applied to the Err variant. Then, the docstring (emphasis mine):

Maps a Result<T, E> to U by applying a fallback function to a contained Err value, or a default function to a contained Ok value.

I think this is a very unfortunate choice of words and should be changed.

[jyn514]

@orlp are you interested in making a PR to fix it? :) there are instructions in https://rustc-dev-guide.rust-lang.org/getting-started.html#building-and-testing-stdcorealloctestproc_macroetc

[orlp]

I could, but I think I'd prefer to bikeshed a bit first as to how it should be described.

[MightyPork]

To me these functions are so confusing that I practically never use them, the arguments are in the wrong order ... as repeatedly noted in both the tracking issue and stabilization PR that added it. It can't be changed, of course :/

I rather like the way it's documented in the corresponding method on Option: https://doc.rust-lang.org/std/option/enum.Option.html#method.map_or_else

[mdsn]

How about

Maps a Result<T, E> to U by applying function f to a contained Ok value, or by applying default to a contained Err value.

It explains in the same order as the function name (ok_or_else) and doesn't overload the meaning of "default" in the context of the unfortunate function argument.

[orlp]

Made a pull request using @mdsn 's suggestion, only replacing "applying default" with "applying function default" to be consistent with the earlier part of the sentence.