Skip to content

Zone, isolates and Worker are poorly documented #17667

@yjbanov

Description

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

Metadata

Metadata

Assignees

No one assigned

    Labels

    area-core-librarySDK core library issues (core, async, ...); use area-vm or area-web for platform specific libraries.core-adocs-apilibrary-asynctype-documentationA request to add or improve documentation

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions