Zone, isolates and Worker are poorly documented

[yjbanov]

What steps will reproduce the problem?

1. https://api.dartlang.org/apidocs/channels/stable/#dart-async.Zone
2. https://api.dartlang.org/apidocs/channels/stable/#dart-isolate
3. https://api.dartlang.org/apidocs/channels/stable/#dart-dom-html.Worker

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".

[kwalrath]

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:
https://zones-dot-dart-lang.appspot.com/articles/zones/

---

Added Docs-API, Area-Library, Library-Async, Triaged labels.

[yjbanov]

Love Florian's articles! Maybe add a link to the article from the API docs for now?

[kwalrath]

Removed Type-Defect label.
Added Type-Documentation label.

[PandaGeek1024]

The article is gone, i will never be able to understand zone.

[maks]

@PandaGeek1024 the article on zones is still available though archived.

[maks]

What I find very undocumented is the interaction between Zones and Isolates.
I'm currently trying to understand why a test I'm trying to write using FakeAsync (which makes use of zones) doesn't seem to work with a stream linked to an isoloates SendPort and there seems to be no documentation at all about how Zones work (or don't) with Isolates.