Address shortcomings in documentation on Isolate class.

sdk/lib/isolate/isolate.dart

Index: sdk/lib/isolate/isolate.dart
diff --git a/sdk/lib/isolate/isolate.dart b/sdk/lib/isolate/isolate.dart
index 8caccdb4e0ac56198ceae436b91e2e68350d3211..cb09da7c8b0e7b3e620e36631752ac3c008477b0 100644
--- a/sdk/lib/isolate/isolate.dart
+++ b/sdk/lib/isolate/isolate.dart
@@ -7,9 +7,9 @@
  * independent workers that are similar to threads
  * but don't share memory,
  * communicating only via messages.
- * 
+ *
  * To use this library in your code:
- * 
+ *
  *     import 'dart:isolate';
  */
 library dart.isolate;
@@ -162,19 +162,27 @@ class Isolate {
    * Creates and spawns an isolate that shares the same code as the current
    * isolate.
    *
-   * The argument [entryPoint] specifies the entry point of the spawned
-   * isolate. It must be a top-level function or a static method that
-   * takes one argument - that is, one-parameter functions that can be
-   * compile-time constant function values.
-   * It is not allowed to pass the value of function expressions or an instance
-   * method extracted from an object.
+   * The argument [entryPoint] specifies the initial function to call
+   * in the spawned isolate.
+   * The entry-point function is invoked in the new isolate with [message]
+   * as the only argument.
+   *
+   * The function must be a top-level function or a static method
+   * that can be called with a single argument -

[eernst, 2016/06/14 11:36:47]

Might as well use ',' because the single hyphen is so different from the proper
em-dash, and a comma would not be unnatural here.

[Lasse Reichstein Nielsen, 2016/07/04 11:47:32]

Done.

+   * that is, a compile-time constant function value
+   * which accepts at least one positional parameter
+   * and has at most one required positional parameter.
+   * The function may accept any number of optional parameters,
+   * as long as they *can* be called with just a single argument.

[eernst, 2016/06/14 11:36:47]

There's a singular/plural issue here, and I also think that the emphasis is
slightly too informal for long time use (this whole sentence is just there for
emphasis), so I'd suggest: 'as long as it can'.

[Lasse Reichstein Nielsen, 2016/07/04 11:47:33]

Done.

+   * The value of a function expressions or a torn-off instance methods are not
+   * allowed.

[eernst, 2016/06/14 11:36:47]

A bit of confusion here, too. Maybe it would work to say 'It is not allowed to
pass a function expression nor an instance method tear-off.'

[Lasse Reichstein Nielsen, 2016/07/04 11:47:33]

You can't pass an expression, only its value.
Reworded to: 
The function must not be the value of a function expression or an instance
method tear-off.

(We don't have a convenient shorthand for those two, but it would probably be
"closure" if we did)

    *
-   * The entry-point function is invoked with the initial [message].
    * Usually the initial [message] contains a [SendPort] so
    * that the spawner and spawnee can communicate with each other.
    *
    * If the [paused] parameter is set to `true`,
    * the isolate will start up in a paused state,
+   * just before calling the [entryPoint] function with the [message],
    * as if by an initial call of `isolate.pause(isolate.pauseCapability)`.
    * To resume the isolate, call `isolate.resume(isolate.pauseCapability)`.
    *
@@ -184,19 +192,22 @@ class Isolate {
    * corresponding parameter and was processed before the isolate starts
    * running.
    *
+   * If [errorsAreFatal] is omitted, the platform may choose a default behavior
+   * or inherit the current isolate's behavior.
+   *
    * You can also call the [setErrorsFatal], [addOnExitListener] and
    * [addErrorListener] methods on the returned isolate, but unless the
    * isolate was started as [paused], it may already have terminated
    * before those methods can complete.
    *
-   * Returns a future that will complete with an [Isolate] instance if the
+   * Returns a future which will complete with an [Isolate] instance if the
    * spawning succeeded. It will complete with an error otherwise.
    */
   external static Future<Isolate> spawn(void entryPoint(message), var message,
-                                        { bool paused: false,
-                                          bool errorsAreFatal,
-                                          SendPort onExit,
-                                          SendPort onError });
+                                        {bool paused: false,
+                                         bool errorsAreFatal,
+                                         SendPort onExit,
+                                         SendPort onError});
 
   /**
    * Creates and spawns an isolate that runs the code from the library with
@@ -291,13 +302,16 @@ class Isolate {
   /**
    * Requests the isolate to pause.
    *
-   * The isolate should stop handling events by pausing its event queue.
-   * The request will eventually make the isolate stop doing anything.
-   * It will be handled before any other messages that are later sent to the
-   * isolate from the current isolate, but no other guarantees are provided.
+   * When the isolate receives the pause command, it will stop

[floitsch, 2016/06/16 08:36:34]

Stops

[Lasse Reichstein Nielsen, 2016/07/04 11:47:33]

Done.

+   * processing events from the event loop queue.
+   * It may still add new events to the queue in response to, e.g., timers
+   * or receive port messages. When the isolate is resumed, it will handle

[floitsch, 2016/06/16 08:36:35]

Maybe "handles" but here it really is in the future.

[Lasse Reichstein Nielsen, 2016/07/04 11:47:32]

Used "handles" and improved the second half of the sentence.

+   * the enqueued events in the order they were enqueued.
    *
-   * The event loop may be paused before previously sent, but not yet exeuted,
-   * messages have been reached.
+   * The pause request is sent through the isolate's command port and will be
+   * handled when it is received, after other previously sent command messages,
+   * but before already enqueued event loop events that hasn't been processed

[eernst, 2016/06/14 11:36:47]

'after any previously sent command messages, but before any enqueued event loop
events.'

If event loop events can indeed be enqueued even though they have already been
processed then we can add 'that have not yet been processed'. Otherwise we might
as well put a period here, and then, possibly, add a separate sentence
explaining that processed events cannot exist in the queue.

[Lasse Reichstein Nielsen, 2016/07/04 11:47:32]

Event loop events are enqueued until they are processed, and that removes them
from the queue. 
So, no, they can't. 
I think a larger rewrite is in order.
The "pause" command (like any command) takes effect before the next event loop
event is processed, but after the current one is done.
(I don't think you pause the microtask queue).

+   * yet.
    *
    * If [resumeCapability] is provided, it is used to identity the pause,
    * and must be used again to end the pause using [resume].