Edit documentation for ReceivePort and Isolate.

corelib/src/isolate.dart

 // Copyright (c) 2011, 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.
 
 // Dart core library.
 
 /**
  * [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].
@@ skipping 60 matching lines @@
   ReceivePort.singleShot();
 
   /**
    * Sets up a callback function for receiving pending or future
    * messages on this receive port.
    */
   void receive(void callback(var message, SendPort replyTo));
 
   /**
    * Closes this receive port immediately. Pending messages will not
-   * be processed and it is impossible to re-open the port. Reply
-   * ports possibly created through [SendPort.call] are automatically
-   * closed when the reply has been received. Multiple invocations of
-   * [close] are allowed but ignored.
+   * be processed and it is impossible to re-open the port. Single-shot
+   * reply ports, such as those created through [SendPort.call], are
+   * automatically closed when the reply has been received. Multiple
+   * invocations of [close] are allowed but ignored.
    */
   void close();
 
   /**
-   * Converts this receive port to a send port. It is legal to create several
-   * [SendPort]s from the same [ReceivePort].
+   * Creates a new send port that sends to this receive port. It is legal to
+   * create several [SendPort]s from the same [ReceivePort].
    */
   SendPort toSendPort();
 
 }
 
 /**
  * The [Isolate] class serves two purposes: (1) as template for spawning a new
  * isolate, and (2) as entry-point for the newly spawned isolate.
  *
  * New isolates are spawned by sub-classing [Isolate] and then invoking
@@ skipping 27 matching lines @@
   Isolate.heavy() : _isLight = false;
 
   /**
    * Spawns a new isolate, using this instance as template.
    *
    * The new isolate lives in a new thread (for heavy templates)
    * or in the same thread as the current isolate (for light templates), if
    * possible.
    *
    * During the initialization of the new isolate a [ReceivePort] is created
-   * inside the new isolate and stored in [port]. A corresponding
-   * [SendPort] is sent to the isolate that invoked [spawn]. Since spawning an
-   * isolate is an asynchronous operation this method returns a [Future] of
-   * this [SendPort].
+   * inside the new isolate and stored in the read-only field [port].
+   *  A corresponding [SendPort] is sent to the isolate that invoked [spawn].
+   * Since spawning an isolate is an asynchronous operation this method returns
+   * a [Future] of this [SendPort].
    *
    * A common pattern to instantiate new isolates is to enqueue the instructions
-   * in [Future.then].
+   * using [Future.then].
    * [:myIsolate.spawn().then((SendPort port) { port.send('hi there'); });:]
    */
   Future<SendPort> spawn() {
     return IsolateNatives.spawn(this, _isLight);
   }
 
   // The private run method is invoked with the receive port. Before
   // main is invoked we store the port in a field so it can be
   // accessed from subclasses of Isolate.
   void _run(ReceivePort port) {
@@ skipping 16 matching lines @@
   /**
    * When isolates are created, an instance of the template's class is
    * instantiated in the new isolate. After the [port] has been set up, this
    * [main] method is invoked on the instance.
    */
   abstract void main();
 
   final bool _isLight;
   ReceivePort _port;
 }