More documentation for zones.

sdk/lib/async/zone.dart

 // Copyright (c) 2013, the Dart project authors.  Please see the AUTHORS file
 // for details. All rights reserved. Use of this source code is governed by a
 // BSD-style license that can be found in the LICENSE file.
 
 part of dart.async;
 
 typedef R ZoneCallback<R>();
 typedef R ZoneUnaryCallback<R, T>(T arg);
 typedef R ZoneBinaryCallback<R, T1, T2>(T1 arg1, T2 arg2);
+
 typedef T TaskCreate<T, S extends TaskSpecification>(
     S specification, Zone zone);
 typedef void TaskRun<T, A>(T task, A arg);
 
 
 // TODO(floitsch): we are abusing generic typedefs as typedefs for generic
 // functions.
 /*ABUSE*/
 typedef R HandleUncaughtErrorHandler<R>(
     Zone self, ZoneDelegate parent, Zone zone, error, StackTrace stackTrace);
@@ skipping 232 matching lines @@
   final PrintHandler print;
   final ForkHandler fork;
 
   @deprecated
   final CreateTimerHandler createTimer;
   @deprecated
   final CreatePeriodicTimerHandler createPeriodicTimer;
 }
 
 /**
  * This class wraps zones for delegation.

[Lasse Reichstein Nielsen, 2016/06/20 21:19:16]

Doesn't make sense.
You can wrap a zone, but not (plural) zones.

It's not wrapping, that implies having the same interface.
Rather it's adapting - except that's an implementation detail and this is an
interface.

So, maybe something like:


* A representation of the "parent" zone of a custom zone.

* Allows the implementation of a zone method to delegate the method call to the
parent zone while retaining knowledge of the originating zone (as the parameter
called `zone`).

Or something like that?

[floitsch, 2016/07/01 04:03:40]

Done.

  *
- * When forwarding to parent zones one can't just invoke the parent zone's
- * exposed functions (like [Zone.run]), but one needs to provide more
- * information (like the zone the `run` was initiated). Zone callbacks thus
- * receive more information including this [ZoneDelegate] class. When delegating
- * to the parent zone one should go through the given instance instead of
- * directly invoking the parent zone.
+ * Custom zones (created through `Zone.fork` or `runZoned`) can provide
+ * implementations of most members of zones. This is similar to overriding

[Lasse Reichstein Nielsen, 2016/06/20 21:19:15]

members of `Zone`?

"members" feels weird, since they are all methods. Just use "methods"?

[floitsch, 2016/07/01 04:03:38]

Done.

+ * methods on [Zone], except that this mechanism doesn't require subclassing.
+ *
+ * A very common operation of intercepting function is to eventually delegate

[Lasse Reichstein Nielsen, 2016/06/20 21:19:16]

Drop "very".
intercepting functions?

But "intercepting" is a new word here and hasn't been explained. I guess you
just mean a member implementation (like mentioned in the previous paragraph), so
keep using the same words for that.

So maybe:

A custom method implementation typically records or wraps its parameters and
then delegates the operation to its parent zone using its provided
[ZoneDelegate]. The alternative is to intercept the call and implement the
functionality without using the parent zone implementation at all.

Because the parent [ZoneDelegate] is provided as a parameter, the same
implementation function can be used in multiple zones.

[floitsch, 2016/07/01 04:03:38]

Done.

+ * to its parent zone. Intercepting functions receive a parent delegate (of
+ * type [ZoneDelegate] for this purpose.
+ *
+ * Providing zone delegates to intercepting functions has two advantages:

[Lasse Reichstein Nielsen, 2016/06/20 21:19:16]

I don't think this belongs in user-directed documentation. We don't need to sell
the implementation, it's already in, and it doesn't help the user use the zone.
Just the facts :)

[floitsch, 2016/07/01 04:03:40]

Reworded.

+ * 1. the intercepting function can provide more information to the parent zone.
+ *   In particular it has to provide the zone in which the action has been
+ *   initiated.
+ * 2. The library can implement the delegates in a more efficient way, since
+ *   it can skip zones that would just delegate to their parents.
+ *
+ * As mentioned in advantage 1, delegates receive a additional arguments.
+ * CONTINUE HERE.
  */
 abstract class ZoneDelegate {
   /*=R*/ handleUncaughtError/*<R>*/(
       Zone zone, error, StackTrace stackTrace);
   /*=R*/ run/*<R>*/(Zone zone, /*=R*/ f());
   /*=R*/ runUnary/*<R, T>*/(Zone zone, /*=R*/ f(/*=T*/ arg), /*=T*/ arg);
   /*=R*/ runBinary/*<R, T1, T2>*/(Zone zone,
       /*=R*/ f(/*=T1*/ arg1, /*=T2*/ arg2), /*=T1*/ arg1, /*=T2*/ arg2);
   ZoneCallback/*<R>*/ registerCallback/*<R>*/(Zone zone, /*=R*/ f());
   ZoneUnaryCallback/*<R, T>*/ registerUnaryCallback/*<R, T>*/(
       Zone zone, /*=R*/ f(/*=T*/ arg));
   ZoneBinaryCallback/*<R, T1, T2>*/ registerBinaryCallback/*<R, T1, T2>*/(
       Zone zone, /*=R*/ f(/*=T1*/ arg1, /*=T2*/ arg2));
   AsyncError errorCallback(Zone zone, Object error, StackTrace stackTrace);
   void scheduleMicrotask(Zone zone, void f());
   Object/*=T*/ createTask/*<T, S>*/(
       Zone zone, TaskCreate/*<T, S>*/ create, TaskSpecification/*=S*/ task);
   void runTask/*T, A*/(
       Zone zone, TaskRun/*<T, A>*/ run, Object/*=T*/ task, Object/*=A*/ arg);
   void print(Zone zone, String line);
   Zone fork(Zone zone, ZoneSpecification specification, Map zoneValues);
 
   @deprecated
   Timer createTimer(Zone zone, Duration duration, void f());
   @deprecated
   Timer createPeriodicTimer(Zone zone, Duration period, void f(Timer timer));
 }
 
 /**
- * A Zone represents the asynchronous version of a dynamic extent. Asynchronous
- * callbacks are executed in the zone they have been queued in. For example,
- * the callback of a `future.then` is executed in the same zone as the one where
- * the `then` was invoked.
+ * A Zone represents an environment that remains stable across asynchronous

[Lasse Reichstein Nielsen, 2016/06/20 21:19:16]

`Zone`

[floitsch, 2016/07/01 04:03:39]

changed to 'zone'.

+ * calls, and which is responsible for handling uncaught asynchronous errors,

[Lasse Reichstein Nielsen, 2016/06/20 21:19:16]

Full stop after "calls", then new paragraph.

The zone is responsible for many things, not just handling uncaught errors, so
maybe something like:

 The zone provides a range of functionality that both platform and user code 
 can access. 
 You can create a new zone that overrides some of the functionality of an
 existing zone. This is similar to creating a new class that extends the 
 base `Zone` class and that overrides some methods, except without actually
 creating a new class. Instead the overriding methods are provided as
 functions that explicitly take the equivalent of their own class, the 
 "super" class and the `this` object as parameters.

 If you override functionality that platform libraries are based on, you can
 modify or replace the behavior of some core, mostly asynchronous, operations.
 This includes creating timers, scheduling microtasks and handling uncaught 
 errors.

(This is technical and should probably go later in the paragraph, after saying
how zones are propagated to async callbacks).

[floitsch, 2016/07/01 04:03:38]

Incorporated (partially) your text.

+ * or operations such as [print] and [scheduleMicrotask].
+ *
+ * Asynchronous callbacks are executed in the zone they have been queued in. For
+ * example, the callback of a `future.then` is executed in the same zone as the
+ * one where the `then` was invoked.
+ *
+ * Code is always executed inside a zone. When a program is started, the

[Lasse Reichstein Nielsen, 2016/06/20 21:19:16]

"inside" feels a little too concrete for me.
How about:

 Code is always executed in the context of a zone, available as [Zone.current].
The initial `main` function runs in the context of the default zone
([Zone.ROOT]). Code can be run in a different zone using either [runZoned], to
create a new zone, or [Zone.run] to run code in the context of an existing zone
likely created using [Zone.fork].

[floitsch, 2016/07/01 04:03:39]

Done.

+ * default zone ([Zone.ROOT]) is installed. Users can provide
+ * shadowing, nested zones.
+ *
+ * The [Zone] class is not subclassable, but users can provide custom zones by
+ * forking an existing zone (usually [Zone.current]) with a [ZoneSpecification].
+ * Zone specifications contain intercepting functions that are invoked when the
+ * zone members are invoked. As such, they provide the same functionality as
+ * subclassing (but allow for a more efficient implementation).
+ *
+ * Asynchronous callbacks always return in the zone in which they have been

[Lasse Reichstein Nielsen, 2016/06/20 21:19:16]

have been -> are

callbacks are functions, when you say that they *return*, it looks like it
refers to where they put their value, not where they actually run (which I think
is what this is about).

Maybe:
 Asynchronous callbacks always run in the context of the zone where they were
scheduled. This is implemented using two steps:
 - The callback is first registered using one of [...]. This allows the zone to
record that a callback exists and to potentially modify the callback. The code
doing the registration (e.g., `Future.then`) also remembers the current zone so
that it can later run the callback in that zone.
 - At a later point the registered callback is actually run in the remembered
zone.

This is all handled internally by the platform code, but if you implement a new
asynchronous operation (<your examples below>), you need to follow the same
protocol to be "zone compatible".

...
(Then the text about where to store the zone (bindCallback etc) fits in)

[floitsch, 2016/07/01 04:03:38]

Done.

+ * scheduled. This happens in two steps:
+ * - the callback is registered using one of [registerCallback],
+ *   [registerUnaryCallback], or [registerBinaryCallback].
+ * - the asynchronous operation (such as [Future.then] or [Stream.listen])
+ *   remember the current zone. Either, they store the zone in a data structure
+ *   (as is done for [Future]s), or they wrap the callback to capture the
+ *   current zone. A convenience function [bindCallback] (and the corresponding
+ *   [bindUnaryCallback] or [bindBindaryCallback]) perform the registration and
+ *   wrapping at the same time.
+ *
+ * Note that all asynchronous primitives (like [Timer.run]) have to be
+ * implemented by the embedder, and that users generally don't need to worry
+ * about keeping track of zones. However, new embedders (or native extensions)
+ * need to ensure that new asynchronous primitives (like for example
+ * `requestAnimationFrame` in the HTML library) respect this contract.
  */
 abstract class Zone {
   // Private constructor so that it is not possible instantiate a Zone class.
   Zone._();
 
-  /** The root zone that is implicitly created. */
+  /**
+   * The root zone that is implicitly created.

[Lasse Reichstein Nielsen, 2016/06/20 21:19:16]

The root zone.

This is the zone that the isolate entry function (`main` or spawn function) runs
in. Asynchronous events inherit the existing zone, so the entire program will
run in this zone if another zone isn't introduced.

[floitsch, 2016/07/01 04:03:39]

somehow incorporated.

+   *
+   * The root zone implements the default behavior of all zone operations.
+   * Many methods, like [registerCallback] don't do anything, others, like
+   * [scheduleMicrotask] interact with the embedder to implement the desired
+   * behavior.
+   */
   static const Zone ROOT = _ROOT_ZONE;
 
   /** The currently running zone. */
   static Zone _current = _ROOT_ZONE;
 
+  /** The zone that is currently active. */
   static Zone get current => _current;
 
+  /**
+   * Handles uncaught asynchronous errors.
+   *
+   * Most asynchronous classes, like [Future] or [Stream] push errors to their
+   * listeners. Errors are propagated this way, until, either a listener handles

[Lasse Reichstein Nielsen, 2016/06/22 14:32:01]

remove both commas.

[floitsch, 2016/07/01 04:03:39]

Done.

+   * the error (for example with [Future.catchError]), or no listener is
+   * available anymore. In the latter case, futures and streams invoke the
+   * zone's [handleUncaughtError].

[Lasse Reichstein Nielsen, 2016/06/22 14:32:03]

Mention that we also handle uncuaght errors from other async callbacks, like
timers.

[floitsch, 2016/07/01 04:03:39]

Reworded.

+   *
+   * By default, in the root zone, uncaught asynchronous errors are treated
+   * like synchronous uncaught exceptions (although the root zone defers the
+   * reporting by a microtask, to give other microtasks the opportunity to run
+   * one last time).

[Lasse Reichstein Nielsen, 2016/06/22 14:32:03]

Actually not.
An uncaught error that hits the uncaught error handler will not reschedule the
error to the end of the microtask queue. It will reschedule to the *front* of
the microtask queue (and multiple errors are queued in order, so the first to
happen is the first to be reported).

The error might have been delayed before getting to the error handler, but once
it hits the uncaught error handler, we don't give other microtasks a chance to
run, we only give the current microtask the chance to complete.
I think we even interrupt _propagateToListeners at an error.

[floitsch, 2016/07/01 04:03:38]

Removed the mention of microtask.

+   */
   /*=R*/ handleUncaughtError/*<R>*/(error, StackTrace stackTrace);
 
   /**
    * Returns the parent zone.
    *
    * Returns `null` if `this` is the [ROOT] zone.
+   *
+   * Zones are created by [fork] (or [runZoned] which forks the [current] zone)
+   * on an existing zone. The new zone keeps the forking zone as [parent] zone.

[Lasse Reichstein Nielsen, 2016/06/22 14:32:01]

Move parentheses to after "an existing zone". Maybe just make it a comma
separated clause then.

"keeps" is vague. Maybe:
"This is the parent zone that this zone was forked from."

(And this getter probably shouldn't have been public either, it's bad for
abstraction).

[floitsch, 2016/07/01 04:03:39]

I don't know anymore why it was added. Probably because we needed it in the
async library...

done.

    */
   Zone get parent;
 
   /**
    * The error zone is the one that is responsible for dealing with uncaught
    * errors.
-   * Errors are not allowed to cross between zones with different error-zones.
    *
-   * This is the closest parent or ancestor zone of this zone that has a custom
+   * This is the closest parent zone of this zone that provides a
    * [handleUncaughtError] method.
+   *
+   * Asynchronous errors never cross zone boundaries of zones with different

[Lasse Reichstein Nielsen, 2016/06/22 14:32:02]

... boundaries between zones ...

[floitsch, 2016/07/01 04:03:38]

Done.

+   * error-zones.

[Lasse Reichstein Nielsen, 2016/06/22 14:32:03]

error-zones -> error handlers.

[floitsch, 2016/07/01 04:03:39]

Done.

+   *
+   * Example:
+   * ```
+   * import 'dart:async';
+   *
+   * main() {
+   *   var future;
+   *   runZoned(() {
+   *     // The asynchronous error is caught by the custom zone which prints
+   *     // 'asynchronous error'.
+   *     future = new Future.error("asynchronous error");
+   *   }, onError: (e) { print(e); });  // Creates a zone with an error handler.
+   *   // The following `catchError` is never reached, because the custom zone

[Lasse Reichstein Nielsen, 2016/06/22 14:32:02]

is never reached -> never sees the error

(sounds like the *call* to catchError is never reached).

[floitsch, 2016/07/01 04:03:38]

Done.

+   *   // that is created by the call to `runZoned` provides an error handler.

[Lasse Reichstein Nielsen, 2016/06/22 14:32:03]

-> custom zone created by `runZoned`

(just because it's shorter)

[floitsch, 2016/07/01 04:03:39]

Done.

+   *   future.catchError((e) { throw "is never reached"; });
+   * }
+   * ```
+   *
+   * Note that errors are not entering zones with different error handlers

[Lasse Reichstein Nielsen, 2016/06/22 14:32:03]

are not entering -> cannot enter
Maybe: *enter* 
(to emphasize).

It's not clear what "entering" means. To me, it's basically "not leaving" where
"leaving" is going from child zone to parent zone (which is the traditional way
for exceptions to flow).
It's crossing the boundary between a zone and another zone that isn't a parent
of the first zone? Or only child zones?

The example is fine, but this is introducing terminology without explaining it.

Maybe: cannot enter -> cannot enter a child zones

[floitsch, 2016/07/01 04:03:40]

Done.

+   * either:
+   * ```
+   * import 'dart:async';
+   *
+   * main() {
+   *   runZoned(() {
+   *     // The following asynchronous error is *not* caught by the `catchError`
+   *     // in the nested zone, since errors are not to cross zone boundaries
+   *     // with different error handlers.
+   *     // Instead the error is handled by the current error handler,
+   *     // printing "Caught by outer zone: asynchronous error".
+   *     var future = new Future.error("asynchronous error");
+   *     runZoned(() {
+   *       future.catchError((e) { throw "is never reached"; });
+   *     }, onError: (e) { throw "is never reached"; });
+   *   }, onError: (e) { print("Caught by outer zone: $e"); });
+   * }
+   * ```
    */
   Zone get errorZone;

[Lasse Reichstein Nielsen, 2016/06/22 14:32:02]

And this shouldn't be public either. :)

[floitsch, 2016/07/01 04:03:39]

That one is definitely used in the async library.

 
   /**
    * Returns true if `this` and [otherZone] are in the same error zone.
    *
    * Two zones are in the same error zone if they inherit their

[Lasse Reichstein Nielsen, 2016/06/22 14:32:03]

Rewrite: if they have the same [errorZone].

[floitsch, 2016/07/01 04:03:40]

Done.

-   * [handleUncaughtError] callback from the same [errorZone].
+   * [errorZone] is the same.
    */
   bool inSameErrorZone(Zone otherZone);
 
   /**
    * Creates a new zone as a child of `this`.
    *
-   * The new zone will have behavior like the current zone, except where
-   * overridden by functions in [specification].
+   * The new zone uses the closures in the given [specification] to override
+   * the current's zone behavior. All specification entries that are `null`
+   * are automatically delegated to the parent zone (`this`).

[Lasse Reichstein Nielsen, 2016/06/22 14:32:03]

Maybe: are automatically delegated to -> inherits the behavior of

(This is a place where I want to emphasize the "like subclassing" methaphor)

[floitsch, 2016/07/01 04:03:38]

Done.

    *
-   * The new zone will have the same stored values (accessed through
+   * The new zone has the same stored values (accessed through
    * `operator []`) as this zone, but updated with the keys and values

[Lasse Reichstein Nielsen, 2016/06/22 14:32:03]

drop "but".
Maybe: The new zone inherits the stored values (accessed through `operator []`)
of this zone and updates them with values from `zoneValues`, which either add
new values or override existing ones.

[floitsch, 2016/07/01 04:03:40]

Done.

    * in [zoneValues]. If a key is in both this zone's values and in
-   * `zoneValues`, the new zone will use the value from `zoneValues``.
+   * `zoneValues`, the new zone uses the value from `zoneValues`.
+   *
+   * Note that the fork operation is interceptible. A zone can thus replace

[Lasse Reichstein Nielsen, 2016/06/22 14:32:02]

replace -> change
(change covers both "modify" and "replace". I tend to read "replace" as "throw
away the old one and create a new from scratch", not as "make a new one that
slightly modifies the existing one", and I want to cover both with this
description).

[floitsch, 2016/07/01 04:03:39]

Done.

+   * the zone specification (or zone value), giving the parent zone full control

[Lasse Reichstein Nielsen, 2016/06/22 14:32:03]

value -> values
parent zone -> forking zone
("parent zone" here could be seen as referring to [parent], not [this], but it's
the latter that is in control of the forking).

[floitsch, 2016/07/01 04:03:40]

Done.

+   * over the child zone.
    */
-  Zone fork({ ZoneSpecification specification,
-              Map zoneValues });
+  Zone fork({ZoneSpecification specification,
+             Map zoneValues});
 
   /**
    * Executes the given function [f] in this zone.

[Lasse Reichstein Nielsen, 2016/06/22 14:32:03]

We should rename `f` to `action` or something non-minimal.
Then:
 Executes [action] in this zone.

[floitsch, 2016/07/01 04:03:40]

Done.

+   *
+   * By default (as implemented in the [ROOT] zone, this updates the [current]

[Lasse Reichstein Nielsen, 2016/06/22 14:32:03]

By default, as implemented in the [ROOT] zone, this runs [action] with this zone
as [current] zone.

(I don't like "update", it makes it sound like "current" is modifiable).

[floitsch, 2016/07/01 04:03:39]

Done.

+   * zone to this zone, and executes [f].

[Lasse Reichstein Nielsen, 2016/06/22 14:32:02]

Add:
If [action] throws, the synchronous exception is not caught by the zone's error
handler. Use [runGuarded] to achieve that.

[floitsch, 2016/07/01 04:03:40]

Done.

+   *
+   * Since the root zone is the only zone that can modify the [current] getter,

[Lasse Reichstein Nielsen, 2016/06/22 14:32:03]

the [current] getter -> the value of [current]

(never refer to a property as a "getter", it might be a field in a later
version).

[floitsch, 2016/07/01 04:03:40]

Done.

+   * custom zones have to delegate to their parent zone if they wish to run

[Lasse Reichstein Nielsen, 2016/06/22 14:32:02]

custom zone intercepting [run] should always delegate the call to their parent
zone, but they can take actions before and after the call.

(No reason to leave the door open - always delegate. If someone breaks that,
they really need to know what they are doing.

[floitsch, 2016/07/01 04:03:38]

Done.

+   * in their zone (which is generally the recommended behavior).
    */
   /*=R*/ run/*<R>*/(/*=R*/ f());
 
   /**
    * Executes the given callback [f] with argument [arg] in this zone.

[Lasse Reichstein Nielsen, 2016/06/22 14:32:02]

arg -> argument
consider f -> action.
(the "no abbreviations" rule)

[floitsch, 2016/07/01 04:03:39]

Done.

+   *
+   * See [run].

[Lasse Reichstein Nielsen, 2016/06/22 14:32:03]

As [run] except that [action] is called with one [argument] instead of none.

[floitsch, 2016/07/01 04:03:38]

Done.

    */
   /*=R*/ runUnary/*<R, T>*/(/*=R*/ f(/*=T*/ arg), /*=T*/ arg);
 
   /**
    * Executes the given callback [f] with argument [arg1] and [arg2] in this

[Lasse Reichstein Nielsen, 2016/06/22 14:32:03]

Executes [action] with two arguments.

As [run] except that [action] is called with the arguments [argument1] and
[argument2] instead of no arguments.

[floitsch, 2016/07/01 04:03:38]

Done.

    * zone.
+   *
+   * See [run].
    */
   /*=R*/ runBinary/*<R, T1, T2>*/(
       /*=R*/ f(/*=T1*/ arg1, /*=T2*/ arg2), /*=T1*/ arg1, /*=T2*/ arg2);
 
   /**
-   * Executes the given function [f] in this zone.
+   * Executes the given function [f] in this zone and catches synchronous

[Lasse Reichstein Nielsen, 2016/06/22 14:32:02]

f->action.

[floitsch, 2016/07/01 04:03:40]

Done.

+   * errors.
    *
-   * Same as [run] but catches uncaught errors and gives them to
-   * [handleUncaughtError].
+   * This function is equivalent to:
+   * ```
+   * try {
+   *   return run(f);

[Lasse Reichstein Nielsen, 2016/06/22 14:32:03]

consider using "this.run" for emphasiz (and "this.handleUncaughtError" below).

[floitsch, 2016/07/01 04:03:39]

Done.

+   * } catch (e, s) {
+   *   return handleUncaughtError(e, s);
+   * }
+   * ```
+   *
+   * See [run].
    */
   /*=R*/ runGuarded/*<R>*/(/*=R*/ f());
 
   /**
-   * Executes the given callback [f] in this zone.
+   * Executes the given callback [f] with argument [arg] in this zone and
+   * catches synchronous errors.
    *
-   * Same as [runUnary] but catches uncaught errors and gives them to
-   * [handleUncaughtError].
+   * See [runGuarded].
    */
   /*=R*/ runUnaryGuarded/*<R, T>*/(/*=R*/ f(/*=T*/ arg), /*=T*/ arg);
 
   /**
-   * Executes the given callback [f] in this zone.
+   * Executes the given callback [f] with arguments [arg1] and [arg2] in this
+   * zone.
    *
-   * Same as [runBinary] but catches uncaught errors and gives them to
-   * [handleUncaughtError].
+   * See [runGuarded].
    */
   /*=R*/ runBinaryGuarded/*<R, T1, T2>*/(
       /*=R*/ f(/*=T1*/ arg1, /*=T2*/ arg2), /*=T1*/ arg1, /*=T2*/ arg2);
 
   /**
    * Registers the given callback in this zone.
    *
    * It is good practice to register asynchronous or delayed callbacks before

[Lasse Reichstein Nielsen, 2016/06/22 14:32:02]

"It is good practice" isn't enough. If you don't, you break zones that needs it.
How about:

When implementing an asynchronous primitive that uses callbacks, a callback must
be registered using this function at the point where the user provides the
callback. This allows zones to record other information that they need at the
same time, perhaps even wrapping the callback, so that the callback is prepared
when it is later run in the same zones (e.g., using [run]).
For example ... 

[floitsch, 2016/07/01 04:03:38]

Done.

    * invoking [run]. This gives the zone a chance to wrap the callback and
    * to store information with the callback. For example, a zone may decide
    * to store the stack trace (at the time of the registration) with the
    * callback.
    *
    * Returns a potentially new callback that should be used in place of the

[Lasse Reichstein Nielsen, 2016/06/22 14:32:02]

Returns the, potentially new, callback that will later be run in the zone.

[floitsch, 2016/07/01 04:03:38]

Done.

    * given [callback].
+   *
+   * Custom zones may intercept this operation.

[Lasse Reichstein Nielsen, 2016/06/22 14:32:02]

Add: The default implementation of [Zone.ROOT] returns the original callback
unchanged.

[floitsch, 2016/07/01 04:03:38]

Done.

    */
   ZoneCallback/*<R>*/ registerCallback/*<R>*/(/*=R*/ callback());
 
   /**
    * Registers the given callback in this zone.
    *
    * Similar to [registerCallback] but with a unary callback.
    */
   ZoneUnaryCallback/*<R, T>*/ registerUnaryCallback/*<R, T>*/(
       /*=R*/ callback(/*=T*/ arg));
@@ skipping 33 matching lines @@
    *      ZoneCallback registered = registerBinaryCallback(f);
    *      if (runGuarded) {
    *        return (arg1, arg2) => this.runBinaryGuarded(registered, arg);
    *      }
    *      return (arg1, arg2) => thin.runBinary(registered, arg1, arg2);
    */
   ZoneBinaryCallback/*<R, T1, T2>*/ bindBinaryCallback/*<R, T1, T2>*/(
       /*=R*/ f(/*=T1*/ arg1, /*=T2*/ arg2), { bool runGuarded: true });
 
   /**
-   * Intercepts errors when added programmatically to a `Future` or `Stream`.
+   * Intercepts errors when added programatically to a `Future` or `Stream`.
    *
-   * When caling [Completer.completeError], [Stream.addError],
+   * When calling [Completer.completeError], [Stream.addError],
    * or [Future] constructors that take an error or a callback that may throw,

[Lasse Reichstein Nielsen, 2016/06/22 14:32:03]

that take a callback that may throw synchronously, or that take an error
directly ...
(to make it clear that it's not the "error that may throw").

[floitsch, 2016/07/01 04:03:40]

Done.

    * the current zone is allowed to intercept and replace the error.
    *
-   * When other libraries use intermediate controllers or completers, such
-   * calls may contain errors that have already been processed.
+   * There is no guarantee that an error is only sent through [errorCallback]
+   * once. Libraries that use intermediate controllers or completers might
+   * end up invoking [errorCallback] multiple times.
    *
-   * Return `null` if no replacement is desired.
-   * The original error is used unchanged in that case.
-   * Otherwise return an instance of [AsyncError] holding
-   * the new pair of error and stack trace.
-   * If the [AsyncError.error] is `null`, it is replaced by a [NullThrownError].
+   * Returns `null` if no replacement is desired. Otherwise returns an instance
+   * of [AsyncError] holding the new pair of error and stack trace.
+   *
+   * Although not recommended, the returned instance may have its `error` member
+   * ([AsyncError.error]) be equal to `null` in which case the error should be
+   * replaced by a [NullThrownError].
+   *
+   * Custom zones may intercept this operation.

[Lasse Reichstein Nielsen, 2016/06/22 14:32:02]

Maybe add:
Implementations of a new asynchronous primitive that converts synchronous errors
to asynchronous errors may want to invoke the `errorCallback` on their zone. If
the error is always passed into an existing future completer or stream
controller, the error will be handled there anyway.

[floitsch, 2016/07/01 04:03:38]

Done.

    */
   AsyncError errorCallback(Object error, StackTrace stackTrace);
 
   /**
    * Runs [f] asynchronously in this zone.

[Lasse Reichstein Nielsen, 2016/06/22 14:32:03]

f -> action, task or callback.

[floitsch, 2016/07/01 04:03:39]

Done.

+   *
+   * The global `scheduleMicrotask` delegates to the current zone's

[Lasse Reichstein Nielsen, 2016/06/22 14:32:01]

(Ick. We need a scope override in DartDoc to be able to refer to the outer
scheduleMicrotask here!)

[floitsch, 2016/07/01 04:03:40]

Acknowledged.

+   * [scheduleMicrotask]. The root zone's implementation interacts with the
+   * embedder to schedule the given callback as microtask.

[Lasse Reichstein Nielsen, 2016/06/22 14:32:02]

embedder -> underlying system

("embedder" is not a term understood by end-users).

[floitsch, 2016/07/01 04:03:38]

Done.

+   *
+   * Custom zones may intercept this operation (for example to wrap the given
+   * callback [f]).
    */
   void scheduleMicrotask(void f());
 
   /**
    * Creates a task, given a [create] function and a [specification].

[Lasse Reichstein Nielsen, 2016/06/22 14:32:03]

That's actually vacuous. It's a function named "createTask" with two parameters,
"create" and "specification", so this line tells us nothing.

How about:

 Creates a task in the current zone.

then go on to describe what a task is before describing what the function does?

That is, if we can describe what a task is, the text below just says which steps
it goes through, but if we use the term, we should be able to define it, even if
it ends up as "a task abstracts over <some vague concept>".

Maybe:
--
A task represents an asynchronous operation or process that reports back by
calling a callback function a number of times, usually at least once unless the
task operation is cancelled.

This function is allows the zone to intercept the initialization of the task
while the [runTask] function allows intercepting a call of the callback
function. An asynchronous operation makes itself interceptable by calling the
zone task methods at the appropriate time.
---

[floitsch, 2016/07/01 04:03:39]

Partially incorporated. In particular I don't want to use "callback" for
'runTask', since that's not really the case. The 'runTask' gets a function that
does an operation. It doesn't need to be a callback.

    *
-   * The [create] function is invoked with the [specification] as argument. It
-   * returns a task object which is used for all future interactions with the
-   * zone.
+   * By default, in the root zone, the [create] function is invoked with the
+   * [specification] as argument. It returns a task object which is used for all
+   * future interactions with the zone. Generally, the object is a unique

[Lasse Reichstein Nielsen, 2016/06/22 14:32:02]

with the zone -> between the zone and the task

[Lasse Reichstein Nielsen, 2016/06/22 14:32:02]

-> The object is a unique instance representing the task, and is generally also
returned to whoever initiated the task.

(It's not just generally unique).

[floitsch, 2016/07/01 04:03:39]

Done.

[floitsch, 2016/07/01 04:03:40]

Done.

+   * instance that is also returned to whoever initiated the action.
+   * For example, the HTML library uses the returned [StreamSubscription] as
+   * task object, when users register an event listener.

[Lasse Reichstein Nielsen, 2016/06/22 14:32:01]

remove comma

[floitsch, 2016/07/01 04:03:40]

Done.

    *
-   * Custom zones may replace the [specification] with a different one, thus
-   * modifying the task parameters.
-   *
-   * Tasks are created when the program is starting an operation that returns
-   * through the event loop. For example, a timer or an http request both
+   * Tasks are created when the program starts an operation that returns
+   * through the event loop. For example, a timer or an HTTP request both

[Lasse Reichstein Nielsen, 2016/06/22 14:32:03]

"return through the event loop" is a clever image, but I don't think it matches
well enough. A periodic timer doesn't "return" because it reports back more than
once.
I prefer "reports back by asynchronously invoking a callback function from the
event loop".

[floitsch, 2016/07/01 04:03:39]

Partially incorporated. Kept the 'return' in the next sentence.

    * return through the event loop and are therefore tasks.
    *
    * If the [create] function is not invoked (because a custom zone has
    * replaced or intercepted it), then the operation is *not* started. This
-   * means that a custom zone can intercept tasks, like http requests.
+   * means that a custom zone can intercept tasks, like HTTP requests.
+   *
+   * A task goes through the following steps:
+   * - a user invokes a library function that should eventually return through
+   *   the event loop (and not just as a microtask).
+   * - the library function creates a [TaskSpecification] that contains the
+   *   necessary information to start the operation, and invokes
+   *   `Zone.current.createTask` with the specification and a [create] closure.
+   *   The closure, when invoked, uses the specification to start the operation
+   *   (usually by interacting with the embedder, ar as a native extension),

[Lasse Reichstein Nielsen, 2016/06/22 14:32:02]

embedder -> underlying system  (everywhere)
ar -> or

[floitsch, 2016/07/01 04:03:40]

Done.

+   *   and returns a task object that identifies the running task.
+   * - custom zones handle the request and (unless completely intercepted and
+   *   aborted), end up calling the root zone's [createTask] which runs the
+   *   provided `create` closure (which may have been replaced at this point).

[Lasse Reichstein Nielsen, 2016/06/22 14:32:02]

parens into comma. (too mmany parenthesized clauses :)

[floitsch, 2016/07/01 04:03:40]

Done.

+   * - later, the asynchronous operation returns through the event loop.
+   *   It invokes [Zone.runTask] on the zone the task should run on (which had

[Lasse Reichstein Nielsen, 2016/06/22 14:32:02]

on the zone in which the task should run (and which was originally passed to the
`create` function by `createTask`).

[floitsch, 2016/07/01 04:03:39]

Done.

+   *   been given to the create function). The [runTask] function receives the
+   *   task object, a `run` function and an argument. As before, custom zones
+   *   may intercept this call. Eventually (unless aborted), the `run` function
+   *   is invoked, running Dart code that has been registered to run when the

[Lasse Reichstein Nielsen, 2016/06/22 14:32:03]

too much "run".
Maybe:

Eventually the `run` function is invoked with the `argument`, unless a custom
zone has aborted it, and that should run the user provided callback.


Actually, this describes the behavior of the [runTask] function in detail. Would
it be better to just refer to that function and describe the behavior there?

[floitsch, 2016/07/01 04:03:39]

Shortened it. I don't want to use 'callback' since that's not always the case.
Sometimes it completes futures, triggers streams ...

I prefer to keep the whole task-description in one place. It makes the doc on
runTask slightly less useful, but should help understand the concepts.

+   *   task returns. This last step may happen multiple times for tasks that are
+   *   not oneshot tasks (see [ZoneSpecification.isOneShot].

[Lasse Reichstein Nielsen, 2016/06/22 14:32:03]

missing end paren.

[floitsch, 2016/07/01 04:03:40]

Done.

+   *
+   * Custom zones may replace the [specification] with a different one, thus
+   * modifying the task parameters.

[Lasse Reichstein Nielsen, 2016/06/22 14:32:02]

Add:
An operation that wishes to be an interceptable task must publicly specify the
types that intercepting code sees:
- The specification type (extending [TaskSpecification]) which holds the
information available when intercepting the `createTask` call.
- The task object type, returned by `createTask` and [create].
- The argument type, if [runTask] takes a meaningful argument.

[floitsch, 2016/07/01 04:03:38]

Done.

    */
   Object/*=T*/ createTask/*<T, S>*/(
       TaskCreate/*<T, S>*/ create, TaskSpecification/*=S*/ specification);

[Lasse Reichstein Nielsen, 2016/06/22 14:32:03]

I would expand function types when used for parameters. it's much more readable
when you can see that "create" is a function, and even see its type directly,
without having to look up "TaskCreate".

Ditto below.

[floitsch, 2016/07/01 04:03:40]

Done.

 
   /**
    * Runs a task callback.
    *
    * This function is invoked, when an operation, started through [createTask],

[Lasse Reichstein Nielsen, 2016/06/22 14:32:01]

remove comma before "when"

[floitsch, 2016/07/01 04:03:38]

Done.

    * returns to Dart code.
    *
    * Generally, tasks schedule Dart code in the global event loop. As such,
    * there is no return value, and [runTask] is a void function.
    *
    * The [task] object must be the same as the one created with [createTask].
    *
    * It is good practice, if task operations provide a meaningful [arg], so
    * that custom zones can deal with it. They might want to log it, or
    * replace it.
+   *
+   * See [createTask].
    */
   void runTask/*<T, A>*/(
       TaskRun/*<T, A>*/ run, Object/*=T*/ task, Object/*=A*/ arg);

[Lasse Reichstein Nielsen, 2016/06/22 14:32:01]

arg->argument.

[floitsch, 2016/07/01 04:03:40]

Done.

 
   /**
    * Creates a Timer where the callback is executed in this zone.
    */
   @deprecated
   Timer createTimer(Duration duration, void callback());
 
   /**
    * Creates a periodic Timer where the callback is executed in this zone.
    */
   @deprecated
   Timer createPeriodicTimer(Duration period, void callback(Timer timer));
 
   /**
    * Prints the given [line].
+   *
+   * The global `print` function delegates to the current zone's [print]
+   * function which makes it possible to intercept the print function.

[Lasse Reichstein Nielsen, 2016/06/22 14:32:03]

intercept the print function -> intercept printing
(or -> intercept calls to the global `print` function).

(There have been two "print function" before in the sentence, so it feels
repetitive and it's not clear which one you intercept).

[floitsch, 2016/07/01 04:03:39]

Done.

+   *
+   * Example:
+   * ```
+   * import 'dart:async';
+   *
+   * main() {
+   *   runZoned(() {
+   *     // Ends up printing: "Intercepted: in zone".
+   *     print("in zone");
+   *   }, zoneSpecification: new ZoneSpecification(
+   *       print: (Zone self, ZoneDelegate parent, Zone zone, String line) {
+   *     parent.print(zone, "Intercepted: $line");
+   *   }));
+   * }
+   * ```
    */
   void print(String line);
 
   /**
    * Call to enter the Zone.
    *
    * The previous current zone is returned.
    */
   static Zone _enter(Zone zone) {
     assert(zone != null);
@@ skipping 955 matching lines @@
                                    handleUncaughtError: errorHandler);
   }
   Zone zone = Zone.current.fork(specification: zoneSpecification,
                                 zoneValues: zoneValues);
   if (onError != null) {
     return zone.runGuarded(body);
   } else {
     return zone.run(body);
   }
 }