Update documentation on `Isolate.removeOnExitListener` and others.

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.
  *
@@ skipping 361 matching lines @@
    * When all active pause requests have been cancelled, the isolate
    * will continue processing events and handling normal messages.
    *
    * If the [resumeCapability] is not one that has previously been used
    * to pause the isolate, or it has already been used to resume from
    * that pause, the resume call has no effect.
    */
   external void resume(Capability resumeCapability);
 
   /**
-   * Asks the isolate to send [response] on [responsePort] when it terminates.
+   * Requests an exist message on [responsePort] when the isolate terminates.
    *
-   * The isolate will send a `response` message on `responsePort` as the last
+   * The isolate will send [response] as a message on [responsePort] as the last
    * thing before it terminates. It will run no further code after the message
    * has been sent.
    *
-   * Adding the same port more than once will only cause it to receive one
-   * message, using the last response value that was added.
+   * Adding the same port more than once will only cause it to receive one exit
+   * message, using the last response value that was added,
+   * and it only needs to be removed once using [removeOnExitListener].
    *
-   * If the isolate is already dead, no message will be sent.
+   * If the isolate is already dead, no exit message will be sent.

[floitsch, 2017/01/30 11:12:14]

is already dead when?
When you add an exit listener?

[Lasse Reichstein Nielsen, 2017/01/30 12:08:13]

Reworded:
 If the isolate has terminated before it can receive this request,
 no exit message will be sent.

    *
    * The [response] object must follow the same restrictions as enforced by
    * [SendPort.send].
    * It is recommended to only use simple values that can be sent to all
    * isolates, like `null`, booleans, numbers or strings.
    *
    * Since isolates run concurrently, it's possible for it to exit before the
    * exit listener is established, and in that case no response will be
    * sent on [responsePort].
    * To avoid this, either use the corresponding parameter to the spawn
    * function, or start the isolate paused, add the listener and
    * then resume the isolate.
    */
   /* TODO(lrn): Can we do better? Can the system recognize this message and
    * send a reply if the receiving isolate is dead?
    */
   external void addOnExitListener(SendPort responsePort, {Object response});
 
   /**
-   * Stop listening on exit messages from the isolate.
+   * Stop listening for exit messages from the isolate.
    *
-   * If a call has previously been made to [addOnExitListener] with the same
-   * send-port, this will unregister the port, and it will no longer receive
-   * a message when the isolate terminates.
-   * A response may still be sent until this operation is fully processed by
-   * the isolate.
+   * Requests for the isolate to not send exit messages on [responsePort].
+   * If the isolate isn't expecting to send exit messages on [responsePort],
+   * because the port hasn't been added using [addOnExitListener],
+   * or because it has already been removed, the request is ignored.
+   *
+   * If the same port has been passed via [addOnExitListener] more than once,
+   * only one call to `removeOnExitListener` is needed to stop it from receiving
+   * exit messagees.
+   *
+   * Closing the receive port at the end of the send port will not stop the
+   * isolate from sending exit messages, they are just going to be lost.
+   *
+   * An exit message may still be sent if the isolate terminates
+   * before this request is received and processed.
    */
   external void removeOnExitListener(SendPort responsePort);
 
   /**
    * Set whether uncaught errors will terminate the isolate.
    *
    * If errors are fatal, any uncaught error will terminate the isolate
    * event loop and shut down the isolate.
    *
    * This call requires the [terminateCapability] for the isolate.
-   * If the capability absent or wrong, no change is made.
+   * If the capability is absent or incorrect, no change is made.
    *
    * Since isolates run concurrently, it's possible for it to exit due to an
    * error before errors are set non-fatal.
    * To avoid this, either use the corresponding parameter to the spawn
    * function, or start the isolate paused, set errors non-fatal and
    * then resume the isolate.
    */
   external void setErrorsFatal(bool errorsAreFatal);
 
   /**
@@ skipping 33 matching lines @@
    * isolates, like `null`, booleans, numbers or strings.
    *
    * If the isolate is alive, it will eventually send `response`
    * (defaulting to `null`) on the response port.
    *
    * The [priority] must be one of [IMMEDIATE] or [BEFORE_NEXT_EVENT].
    * The response is sent at different times depending on the ping type:
    *
    * * `IMMEDIATE`: The isolate responds as soon as it receives the
    *     control message. This is after any previous control message
-   *     from the same isolate has been received, but may be during
-   *     execution of another event.
+   *     from the same isolate has been received and processed,
+   *     but may be during execution of another event.
    * * `BEFORE_NEXT_EVENT`: The response is scheduled for the next time
    *     control returns to the event loop of the receiving isolate,
    *     after the current event, and any already scheduled control events,
    *     are completed.
    */
   external void ping(SendPort responsePort, {Object response,
                                              int priority: IMMEDIATE});
 
   /**
    * Requests that uncaught errors of the isolate are sent back to [port].
    *
    * The errors are sent back as two elements lists.
    * The first element is a `String` representation of the error, usually
    * created by calling `toString` on the error.
    * The second element is a `String` representation of an accompanying
    * stack trace, or `null` if no stack trace was provided.
    * To convert this back to a [StackTrace] object, use [StackTrace.fromString].
    *
-   * Listening using the same port more than once does nothing. It will only
-   * get each error once.
+   * Listening using the same port more than once does nothing.
+   * A port will only receive each error once,
+   * and will only need to be removed once using [removeErrorListener].
    *
    * Since isolates run concurrently, it's possible for it to exit before the
    * error listener is established. To avoid this, start the isolate paused,
    * add the listener and then resume the isolate.
    */
   external void addErrorListener(SendPort port);
 
   /**
-   * Stop listening for uncaught errors through [port].
+   * Stop listening for uncaught errors from the isolate.
    *
-   * The `port` should be a port that is listening for errors through
-   * [addErrorListener]. This call requests that the isolate stops sending
-   * errors on the port.
+   * Requests for the isolate to not send uncaught errors on [responsePort].
+   * If the isolate isn't expecting to send uncaught errors on [responsePort],
+   * because the port hasn't been added using [addErrorListener],
+   * or because it has already been removed, the request is ignored.
    *
-   * If the same port has been passed via `addErrorListener` more than once,
+   * If the same port has been passed via [addErrorListener] more than once,
    * only one call to `removeErrorListener` is needed to stop it from receiving
-   * errors.
+   * unaught errors.
    *
    * Closing the receive port at the end of the send port will not stop the
-   * isolate from sending errors, they are just going to be lost.
+   * isolate from sending uncaught errors, they are just going to be lost.
+   *
+   * Uncaught errors message may still be sent by the isolate
+   * until this request is received and processed.
    */
   external void removeErrorListener(SendPort port);
 
   /**
    * Returns a broadcast stream of uncaught errors from the isolate.
    *
    * Each error is provided as an error event on the stream.
    *
    * The actual error object and stackTraces will not necessarily
    * be the same object types as in the actual isolate, but they will
@@ skipping 174 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;
 }