Improve documentation of Isolate.current.

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 424742a15b1d47dbc07d9d6df02f2e9de88d0807..f33b63c6507cc591b6e6226724335358aa15f191 100644
--- a/sdk/lib/isolate/isolate.dart
+++ b/sdk/lib/isolate/isolate.dart
@@ -137,11 +137,18 @@ class Isolate {
                              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;