Improve documentation of Isolate.current.

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 119 matching lines @@
    * untrustedCode(restrictedIsolate);
    * ```
    * This example creates a new `Isolate` object that cannot be used to
    * pause or terminate the isolate. All the untrusted code can do is to
    * inspect the isolate and see uncaught errors or when it terminates.
    */
   Isolate(this.controlPort, {this.pauseCapability,
                              this.terminateCapability});
 
   /**
-   * Return the current [Isolate].
+   * Return an [Isolate] object representing the current isolate.
    *
-   * The isolate gives access to the capabilities needed to inspect,
+   * The current isolate for code using [current]
+   * is the isolate running the code.
+   *
+   * The isolate object provides the capabilities required to inspect,
    * pause or kill the isolate, and allows granting these capabilities
    * to others.
+   *
+   * It is possible to pause the current isolate, but doing so *without*
+   * first passing the ability to resume it again to another isolate,
+   * is a sure way to hang your program.
    */
   external static Isolate get current;
 
   /**
    * Returns the package root of the current isolate, if any.
    *
    * If the isolate is using a [packageConfig] or the isolate has not been
    * setup for package resolution, this getter returns `null`, otherwise it
    * returns the package root - a directory that package URIs are resolved
    * against.
@@ skipping 542 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;
 }