Add one-line description to dart:isolate, plus a start at doc comment cleanup.

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_:
+ * threads of execution that communicate via messages.

[sethladd, 2013/08/21 17:23:18]

threads are an overloaded term. can we find a better term?

[Kathy Walrath, 2013/08/21 17:44:24]

The reason that I included it is because some people might search for "thread"
in the page. We could do instead:

1. independent threads of execution that...
2. independent, thread-like units of execution that...
3. thread-like units of execution that...

I'm not crazy about any of those, but #1 seems better because it doesn't assume
knowledge of threads.

Another term people might know that we could use might be "worker". Maybe:

4. independent workers that are similar to threads of execution but don't share
memory,
communicating only via messages.

Which one do you prefer? Can you think of something better?

[sethladd, 2013/08/21 19:16:42]

"Concurrent code that communicates via message passing."

?

[Kathy Walrath, 2013/08/21 21:23:10]

No mention of "worker" or "thread"?

+ *
+ * See also:
+ * [dart:isolate - Concurrency with Isolates](https://www.dartlang.org/docs/dart-up-and-running/contents/ch03.html#ch03-dartisolate---concurrency-with-isolates)
+ * in the library tour.
+ */
 library dart.isolate;
 
 import "dart:async";
 
 part "isolate_stream.dart";
 
 class IsolateSpawnException implements Exception {
   const IsolateSpawnException(String this._s);
   String toString() => "IsolateSpawnException: '$_s'";
   final String _s;
 }
 
 /**
- * The initial [ReceivePort] available by default for this isolate. This
- * [ReceivePort] is created automatically and it is commonly used to establish
- * the first communication between isolates (see [spawnFunction] and
- * [spawnUri]).
+ * The initial ReceivePort available by default for this isolate.
+ *
+ * This ReceivePort is created automatically
+ * and is commonly used to establish
+ * the first communication between isolates.
+ * (See [spawnFunction] and [spawnUri].)
  */
 ReceivePort get port => _Isolate.port;
 
 /**
- * Creates and spawns an isolate that shares the same code as the current
- * isolate, but that starts from [topLevelFunction]. The [topLevelFunction]
- * argument must be a static top-level function or a static method that takes no
+ * Creates and spawns an isolate
+ * that shares the same code as the current isolate,
+ * but that starts from the specified function.
+ *
+ * The [topLevelFunction] argument must be
+ * a static top-level function or a static method that takes no
  * arguments. It is illegal to pass a function closure.
  *
  * When any isolate starts (even the main script of the application), a default
  * [ReceivePort] is created for it. This port is available from the top-level
  * getter [port] defined in this library.
  *
- * [spawnFunction] returns a [SendPort] derived from the child isolate's default
- * port.
+ * This function returns a [SendPort] derived from
+ * the child isolate's default port.
  *
  * The optional [unhandledExceptionCallback] argument is invoked whenever an
  * exception inside the isolate is unhandled. It can be seen as a big
  * `try/catch` around everything that is executed inside the isolate. The
- * callback should return `true` when it was able to handled the exception.
+ * callback should return `true` if it was able to handle the exception.
  */
 SendPort spawnFunction(void topLevelFunction(),
     [bool unhandledExceptionCallback(IsolateUnhandledException e)])
     => _Isolate.spawnFunction(topLevelFunction, unhandledExceptionCallback);
 
 /**
- * Creates and spawns an isolate whose code is available at [uri].  Like with
- * [spawnFunction], the child isolate will have a default [ReceivePort], and a
- * this function returns a [SendPort] derived from it.
+ * Creates and spawns an isolate that runs the code from the specified URI.
+ *
+ * As with [spawnFunction],
+ * the child isolate has a default [ReceivePort],
+ * and this function returns a [SendPort] derived from it.
  */
 SendPort spawnUri(String uri) => _Isolate.spawnUri(uri);
 
 /**
+ * Together with [ReceivePort],
+ * the only means of communication between isolates.
+ *
  * [SendPort]s are created from [ReceivePort]s. Any message sent through
  * a [SendPort] is delivered to its respective [ReceivePort]. There might be
  * many [SendPort]s for the same [ReceivePort].
  *
  * [SendPort]s can be transmitted to other isolates.
  */
 abstract class SendPort {
 
   /**
    * Sends an asynchronous [message] to this send port. The message is copied to
@@ skipping 33 matching lines @@
 
   /**
    * Returns an immutable hash code for this send port that is
    * consistent with the == operator.
    */
   int get hashCode;
 
 }
 
 /**
- * [ReceivePort]s, together with [SendPort]s, are the only means of
- * communication between isolates. [ReceivePort]s have a [:toSendPort:] method
+ * Together with [SendPort], the only means of
+ * communication between isolates.
+ *
+ * [ReceivePort]s have a [:toSendPort:] method
  * which returns a [SendPort]. Any message that is sent through this [SendPort]
  * is delivered to the [ReceivePort] it has been created from. There, they are
  * dispatched to the callback that has been registered on the receive port.
  *
  * A [ReceivePort] may have many [SendPort]s.
  */
 abstract class ReceivePort {
 
   /**
    * Opens a long-lived port for receiving messages. The returned port
@@ skipping 78 matching lines @@
   const IsolateUnhandledException(this.message, this.source, this.stackTrace);
 
   String toString() {
     return 'IsolateUnhandledException: exception while handling message: '
         '${message} \n  '
         '${source.toString().replaceAll("\n", "\n  ")}\n'
         'original stack trace:\n  '
         '${stackTrace.toString().replaceAll("\n","\n  ")}';
   }
 }