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

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 49c0eb82b6ec79a044575f47a495bd079713d570..37fefc720fa38f674e56d4119c905a7d9509bf1f 100644
--- a/sdk/lib/isolate/isolate.dart
+++ b/sdk/lib/isolate/isolate.dart
@@ -2,6 +2,14 @@
 // 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";
@@ -15,43 +23,53 @@ class IsolateSpawnException implements Exception {
 }
 
 /**
- * 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].
@@ -105,8 +123,10 @@ abstract class SendPort {
 }
 
 /**
- * [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.