array::from_fn behavior is unclear from documentation

[jgao222]

Location

https://doc.rust-lang.org/std/array/fn.from_fn.html and https://doc.rust-lang.org/core/array/fn.from_fn.html

Summary

The documentation for from_fn states

Creates an array [T; N] where each array element T is returned by the cb call.

Arguments

• cb: Callback where the passed argument is the current array index.

It is not clear what "current array index" refers to, since the function description doesn't necessarily indicate that there is iteration happening to create the resulting array.

Additionally, the first line summary doesn't actually reflect the behavior of the function at all. It mentions "the cb call" -- as if there is only one call to cb.

I think would be more clear if the documentation somehow mentioned that the i-th element in the output array is the result of calling cb(i).

The function try_from_fn is similarly unclear. Anyone have thoughts on this?

[vacuus]

I'm not sure if the Arguments section helps, since it separates the description of the callback somewhat. I think it should all be at the same visual level. Juxtaposing T next to "array element" also seems weird. How about:

Creates an array of type [T; N], where each element is the result of calling cb with that element's index.

(Maybe "returned value from" instead of "result of"?)

[scottmcm]

They're both the same function (std is a re-export of the core one), so https://doc.rust-lang.org/nightly/std/array/fn.from_fn.html is a sufficient link.

I agree the "Arguments" section is pretty unusual (I don't remember seeing it on anything else), and I'm not sure that "callback" is a usual word here. iter::from_fn looks like it just uses f for the generator, FWIW.

The "Examples" section does, I think, really help clarify what it's going to do. But both the prose and the examples could due with some expansion. For example, this should probably get a guarantee of the order in which the items are generated, since it takes impl FnMut, and a corresponding example, though additional guarantees like that take a libs-api sign-off.

Oh, and I might as well cc #100462, which is open with some other suggested improvements.

[vacuus]

I don't know about how best to document the type inference in the other issue (though, to throw my 2¢ in, I'm not sure it needs documentation :), but you raise a good point about impl FnMut and ordering. Assuming the guarantee of the order of arguments:

Creates an array of type [T; N], where each element is the result of calling cb with that element's index. It is guaranteed that the index ranges from 0 to the end of the array.

Is "the end of the array" interchangeable with N - 1? Is N - 1 clearer? I'm also unsure about explicitly mentioning the index 0 because of zero-length arrays. Instead of explicitly using numbers, maybe an analogue of iteration can be described. I'm not sure if accurately describing that can avoid expose implementation details and/or uninitialized memory, though.

[scottmcm]

Consider writing out pseudocode as well, as that can be more helpful than prose for some people.

For example, you could rename the function to gen, and describe it as

[gen(0), gen(1), gen(2), …, gen(N-2), gen(N-1)]

That's pretty accurate, and the … should have them understand that it's not literally 0 or N-1 or anything.

But your note about N == 0 is a good one. Edge cases are a good thing to mention explicitly even if not strictly necessary. For example, you could mention that "If N == 0, an empty array will be returned and the the closure will never be called".

You could also describe it by analogy to other things. For example, this is in a way the eager version of (0..N).map(gen).

[HintringerFabian]

@rustbot claim