elaborate on TaskPool and bevy tasks #8750
Conversation
I found it very difficult to understand how bevy tasks work, and these changes to the documentation were written from my beginner's perspective after some extremely helpful explanations by nil on Discord.
|
Note that I have not checked if the docs render correctly, but I hope this PR is useful nonetheless. |
|
I just realized that I may even have been mislead by the
"allowing it to continue running without having to be polled by the end-user" actually sounds as if tasks on which one did not call detach() require polling to be executed, don't you agree? I am not trying to nit-pick here, I hope that's clear – I am just trying to debug why I struggled so much with building a mental model of what bevy_tasks does. |
alice-i-cecile
added
C-Docs
|
I have fixed the style and tried to address the spawn() docs issue. I still think that the blurp at the top of |
|
So, those are module level docs for the In this case, I think that the right fix is actually to grab all of those docs and move them to the top-level |
The non-public `usages` module contained useful documentation that is missing from the published docs, and that is in fact good for the `bevy_tasks` front page.
|
I did so, and also rendered the docs locally and did some final polishing. |
|
Hmm, stupid question: Should I fix typos in extra commits or force-push a squashed version? |
|
Extra commits are my preference, but we don't enforce commit style. I tend to find it makes things easier for reviewers to follow, and the commit history on |
I noticed that I accidentally "fixed" what I thought were missing full stops after the summary phrase / paragraph at the beginning of the pool struct documentation. However, these summaries appear on the top level bevy_tasks docs in some kind of table, where those periods would not be desirable.
"A few points" sounds as if there was more to be done than the WASM sentence? :-) |
alice-i-cecile
added
the
S-Ready-For-Final-Review
Co-authored-by: Mike <mike.hsu@gmail.com>
Objective
I found it very difficult to understand how bevy tasks work, and I concluded that the documentation should be improved for beginners like me.
Solution
These changes to the documentation were written from my beginner's perspective after
some extremely helpful explanations by nil on Discord.
I am not familiar enough with rustdoc yet; when looking at the source, I found the documentation at the very top of
usages.rshelpful, but I don't know where they are rendered. They should probably be linked to from the mainbevy_tasksREADME.