Improve comment for FuturesOrdered and FuturesUnordered

[th4s]

For FuturesOrdered there is a comment that says the futures would run in parallel, which is misleading.

This PR makes clear that futures for FuturesOrdered and FuturesUnordered run to completion concurrently instead of parallel.

[taiki-e]

Thanks for the PR! As #2541 mentioned, it might be a good idea to mention how to run them in parallel.

Also, could you improve the comments on the APIs mentioned in #2541 as well?

[th4s]

What would be the correct approach to run them in parallel? I assume you have to spawn them as tasks, but this should probably be runtime-agnostic? What is the correct way to do this? Is it this one https://docs.rs/futures-util/latest/futures_util/task/trait.SpawnExt.html#method.spawn_with_handle ?

[taiki-e]

Hmm, I’m not sure if there is a good way to do that without depending on an executor/runtime.

[th4s]

So by "mention how to run them in parallel" you mean I should just add the comment that one needs to invoke spawn on a runtime, or what do you have in mind?

[vasilakisfil]

I think this PR is helpful. There is some vagueness in existing docs as to what these 2 types are, and I think this PR makes it better.

As #2541 mentioned, it might be a good idea to mention how to run them in parallel.

@taiki-e I am also a bit confused by your comment. In order to run them in parallel you would have to spawn tasks, and this feels a bit out of context.

[taiki-e]

I am also a bit confused by your comment. In order to run them in parallel you would have to spawn tasks, and this feels a bit out of context.

The author of #2541 seems to think that a document that states "concurrent but not parallel" should also state "how to run in parallel" and I basically agree with that.

However, if that is difficult, simply stating "concurrent but not parallel" would be fine.

[rustbot]

☔ The latest upstream changes (possibly #3001) made this pull request unmergeable. Please resolve the merge conflicts.