-
Notifications
You must be signed in to change notification settings - Fork 1.7k
Zone, isolates and Worker are poorly documented #17667
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Comments
True enough. We should probably split this bug up since it covers several areas. For now, I've assigned it to the dart:async library. Note that Florian has written a Zones article, which you can preview (in draft form) at: Added Docs-API, Area-Library, Library-Async, Triaged labels. |
Love Florian's articles! Maybe add a link to the article from the API docs for now? |
Removed Type-Defect label. |
The article is gone, i will never be able to understand zone. |
@PandaGeek1024 the article on zones is still available though archived. |
What I find very undocumented is the interaction between Zones and Isolates. |
What steps will reproduce the problem?
Zone
The documentation is not detailed. The concepts are defined via uncommon terms. For example, Zone is defined via "dynamic extent", which is not a common term (only that it comes from Common Lisp :), sorry couldn't resist). Same goes for the concepts "bind" and "register". The docs use casual language (e.g. "gives the zone a chance to wrap the callback", or "asynchronous version of"), which is ok to get an intuitive sense of what they mean, but they should be backed by details using a stricter language. Some terms are defined recursively (e.g. registerCallback "registers the given callback"), which is not helpful.
isolates
It's safe to say this library is not documented at all. The link provided at the top is broken. It probably meant to link to https://www.dartlang.org/docs/dart-up-and-running/contents/ch02.html#isolates, but even there you won't find any details.
Worker
The docs are an excerpt from MDN, which document the JavaScript API. For instance, Dart doesn't have XMLHttpRequest. There is also no discussion about the differences between isolates and workers. In fact the docs for isolates overload the meaning of "worker" by describing isolates as "independent workers".
The text was updated successfully, but these errors were encountered: