Describe the return value of `Stream.each/2` in its docs?

[Kenny Evitt]

I just asked this question on SO earlier today: https://stackoverflow.com/questions/72398087/difference-between-stream-each-2-and-stream-map-2/72399182#72399182

I'd guess it might be nice for others too if the docs included something like "Returns the original enumerable" or "Returns the given enumerable".

I can make a PR to update the docs if that's okay.

One of the answers on the SO question pointed out that `Stream.each/2` returning the original enumerable was very handy for inspecting elements in a pipeline. Now that they pointed that out to me, I'm curious why `Enum.each/2` doesn't do the same thing?

I think I was previously confused as to what `Stream.each/2` was returning _because_ `Enum.each/2` returns `:ok` instead and I expected the former to mirror the latter.

[Kenny Evitt]

Other commenters on the SO question have pointed out good reasons why `Stream.each/2` differs from `Enum.each/2`, e.g. that `Enum.each/2` can be used for enumerables for which it _wouldn't_ make sense to (always) return them (e.g. because of memory usage).

Is any of this info – or this _kind_ of info – worth adding to the docs, either for `Stream.each/2` or `Enum.each/2`?

Or was/am I just missing some important background/context that would have made all of this more obvious to me initially? (And is there any value to maybe pointing to that background/context in the docs for either?)

[Christopher Keele]

I think expanding on the `Stream.each/2` docs to clarify that it returns the provided enumerable unchanged, and pointing to `Stream.map/2` if producing a modified stream is desired, would be a welcome enhancement!

[Kenny Evitt]

Finally!: https://github.com/elixir-lang/elixir/pull/11941