Sdk: Provide documentation on how to use web workers for Dart 2

[mnordine]

Dart SDK Version 2
Windows, MacOS
Chrome

I decided to try out Dart 2, and one of the first things I wanted to look into is how to run workers on the web, since Isolate is no longer available for the web. Here is the documentation: https://api.dartlang.org/stable/2.0.0/dart-html/Worker-class.html

There is no indication whatsoever on how to proceed on such an important web feature, given the ever-increasing importance of concurrent computation on modern systems.

Some questions that immediately spring to mind:

• JS Worker and Dart Worker take a script url
• How does that work?
• Do I pass in a Dart url?
• If so, what does that Dart file look like?
• Can I pass in a function instead of a script url?

In a more general sense, Dart documentation for web APIs is not a good experience. Are those docs simply generated from browser IDL? Those docs should contain API overview, working examples for each function where not immediately obvious, links to articles, etc...Almost every page I visit is just method and property names. There's no guidance for the programmer.

[kwalrath]

/cc @kevmoo @vsmenon

[rayk]

Yet certainly needed... Just posted this on slack, have spent too much time on stuff that should be simple.

[rayk]

A somewhat related issue, https://github.com/dart-lang/sdk/issues/35730 concerning web workers. This area is ripe for some programmer guidance.

[mnordine]

I see the same thing over and over in the wild, programmers with no guidance on how to use Web Workers (does it even work with Dart 2?) trying to come up with hacks, left to their own devices:
https://medium.com/@yuankuan/web-worker-and-dart-ef76eab562e6
https://medium.com/@yuankuan/web-worker-and-dart-2-5f38ba74575c

[kevmoo]

See https://github.com/dart-lang/sdk/issues/35730#issuecomment-456681047 – @sigmundch is running on this!

[bergwerf]

Yeah I would also like some documentation/examples on this.

[srawlins]

Throwing this over to web (@vsmenon ) to see what they think the solution is: better API docs on the Worker class? An article?

[mnordine]

I think the kicker here is web workers don't work with DDC: https://github.com/dart-lang/sdk/issues/36295