The current docs for bevy::tasks and the pools explains what each task pool should be used for in a short sentence, but doesn't go deeper than that. This leaves open some questions users might have about when to use which pool, as was the case with me. What exactly does tasks spend very little time in a "woken" state mean for the kinds of code? Is it enough to call std::thread::yield_now or is a std::thread::sleep necessary to be considered "not in a woken state"? How does it interact with std::thread::park(_timeout)? What about on other platforms like web, how can i make sure my code for a IoTaskPool is properly not in a "woken" state there, or with single threaded executor?

This might just be a lack of knowledge about threading internals on my end, but on the other hand it seems like knowledge that shouldn't be necessary to understand bevys task pool abstractions.

Normally, i'd look at the code and try to find out what it actually does, but from reading the code its a bit hard to tell what the differences between pools are. To me, the taskpool! macro in bevy_tasks/usages.rs seems to create newtypes around the same TaskPool without any differences between them.

Docs that could be improved: IoTaskPool, AsyncComputeTaskPool and bevy::tasks

Comments that would be nice to have: on the taskpool! macro, explaining how it generates different code, or why all task pools created by it are equivalent.