Address shortcomings in documentation on Isolate class.

sdk/lib/isolate/isolate.dart

 // Copyright (c) 2012, 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.
 
 /**
  * Concurrent programming using _isolates_:
  * 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;
 
 import "dart:async";
 
 part "capability.dart";
 
 /**
  * Thrown when an isolate cannot be created.
@@ skipping 132 matching lines @@
    * If there is no valid mapping from the package: URI in the current
    * isolate, then this call returns `null`. Non-package: URIs are
    * returned unmodified.
    */
   external static Future<Uri> resolvePackageUri(Uri packageUri);
 
   /**
    * 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 entry-point function is invoked with the initial [message].
+   * 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)

+   *
    * 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)`.
    *
    * If the [errorAreFatal], [onExit] and/or [onError] parameters are provided,
    * the isolate will act as if, respectively, [setErrorsFatal],
    * [addOnExitListener] and [addErrorListener] were called with the
    * 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
    * the specified URI.
    *
    * The isolate starts executing the top-level `main` function of the library
    * with the given URI.
    *
    * The target `main` must be callable with zero, one or two arguments.
    * Examples:
@@ skipping 74 matching lines @@
        bool errorsAreFatal,
        bool checked,
        Map<String, String> environment,
        Uri packageRoot,
        Uri packageConfig,
        bool automaticPackageResolution: false});
 
   /**
    * 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].
    * Otherwise a new resume capability is created and returned.
    *
    * If an isolate is paused more than once using the same capability,
    * only one resume with that capability is needed to end the pause.
    *
    * If an isolate is paused using more than one capability,
    * they must all be individully ended before the isolate resumes.
@@ skipping 345 matching lines @@
  * as the original error, but has no other features of the original error.
  */
 class RemoteError implements Error {
   final String _description;
   final StackTrace stackTrace;
   RemoteError(String description, String stackDescription)
       : _description = description,
         stackTrace = new StackTrace.fromString(stackDescription);
   String toString() => _description;
 }