1 files changed, 33 insertions, 30 deletions

diff --git a/graphics/java/android/renderscript/RenderScript.java b/graphics/java/android/renderscript/RenderScript.java
index 8071073a1ac7..4de4766577c4 100644
--- a/graphics/java/android/renderscript/RenderScript.java
+++ b/graphics/java/android/renderscript/RenderScript.java
@@ -33,15 +33,14 @@ import android.os.SystemProperties;
 import android.os.Trace;
 
 /**
- * Renderscript base master class.  An instance of this class creates native
- * worker threads for processing commands from this object.  This base class
- * does not provide any extended capabilities beyond simple data processing.
- * For extended capabilities use derived classes such as RenderScriptGL.
+ * This class provides access to a RenderScript context, which controls RenderScript
+ * initialization, resource management, and teardown. An instance of the RenderScript
+ * class must be created before any other RS objects can be created.
  *
  * <div class="special reference">
  * <h3>Developer Guides</h3>
- * <p>For more information about creating an application that uses Renderscript, read the
- * <a href="{@docRoot}guide/topics/renderscript/index.html">Renderscript</a> developer guide.</p>
+ * <p>For more information about creating an application that uses RenderScript, read the
+ * <a href="{@docRoot}guide/topics/renderscript/index.html">RenderScript</a> developer guide.</p>
  * </div>
  **/
 public class RenderScript {
@@ -912,11 +911,14 @@ public class RenderScript {
     //
 
     /**
-     * Base class application should derive from for handling RS messages
-     * coming from their scripts.  When a script calls sendToClient the data
-     * fields will be filled in and then the run method called by a message
-     * handling thread.  This will occur some time after sendToClient completes
-     * in the script.
+     * The base class from which an application should derive in order
+     * to receive RS messages from scripts. When a script calls {@code
+     * rsSendToClient}, the data fields will be filled, and the run
+     * method will be called on a separate thread.  This will occur
+     * some time after {@code rsSendToClient} completes in the script,
+     * as {@code rsSendToClient} is asynchronous. Message handlers are
+     * not guaranteed to have completed when {@link
+     * android.renderscript.RenderScript#finish} returns.
      *
      */
     public static class RSMessageHandler implements Runnable {
@@ -927,9 +929,10 @@ public class RenderScript {
         }
     }
     /**
-     * If an application is expecting messages it should set this field to an
-     * instance of RSMessage.  This instance will receive all the user messages
-     * sent from sendToClient by scripts from this context.
+     * If an application is expecting messages, it should set this
+     * field to an instance of {@link RSMessageHandler}.  This
+     * instance will receive all the user messages sent from {@code
+     * sendToClient} by scripts from this context.
      *
      */
     RSMessageHandler mMessageCallback = null;
@@ -953,9 +956,9 @@ public class RenderScript {
     }
 
     /**
-     * Runtime error base class.  An application should derive from this class
-     * if it wishes to install an error handler.  When errors occur at runtime
-     * the fields in this class will be filled and the run method called.
+     * The runtime error handler base class.  An application should derive from this class
+     * if it wishes to install an error handler.  When errors occur at runtime,
+     * the fields in this class will be filled, and the run method will be called.
      *
      */
     public static class RSErrorHandler implements Runnable {
@@ -968,7 +971,7 @@ public class RenderScript {
     /**
      * Application Error handler.  All runtime errors will be dispatched to the
      * instance of RSAsyncError set here.  If this field is null a
-     * RSRuntimeException will instead be thrown with details about the error.
+     * {@link RSRuntimeException} will instead be thrown with details about the error.
      * This will cause program termaination.
      *
      */
@@ -982,10 +985,9 @@ public class RenderScript {
     }
 
     /**
-     * RenderScript worker threads priority enumeration.  The default value is
-     * NORMAL.  Applications wishing to do background processing such as
-     * wallpapers should set their priority to LOW to avoid starving forground
-     * processes.
+     * RenderScript worker thread priority enumeration.  The default value is
+     * NORMAL.  Applications wishing to do background processing should set
+     * their priority to LOW to avoid starving forground processes.
      */
     public enum Priority {
         LOW (Process.THREAD_PRIORITY_BACKGROUND + (5 * Process.THREAD_PRIORITY_LESS_FAVORABLE)),
@@ -1052,7 +1054,7 @@ public class RenderScript {
                     }
                     if (mRS.nContextGetUserMessage(mRS.mContext, rbuf) !=
                         RS_MESSAGE_TO_CLIENT_USER) {
-                        throw new RSDriverException("Error processing message from Renderscript.");
+                        throw new RSDriverException("Error processing message from RenderScript.");
                     }
 
                     if(mRS.mMessageCallback != null) {
@@ -1137,7 +1139,7 @@ public class RenderScript {
     }
 
     /**
-     * Create a basic RenderScript context.
+     * Create a RenderScript context.
      *
      * @hide
      * @param ctx The context.
@@ -1163,7 +1165,7 @@ public class RenderScript {
     }
 
     /**
-     * Create a basic RenderScript context.
+     * Create a RenderScript context.
      *
      * @param ctx The context.
      * @return RenderScript
@@ -1173,7 +1175,7 @@ public class RenderScript {
     }
 
     /**
-     * Create a basic RenderScript context.
+     * Create a RenderScript context.
      *
      *
      * @param ctx The context.
@@ -1196,8 +1198,8 @@ public class RenderScript {
     }
 
     /**
-     * Wait for any commands in the fifo between the java bindings and native to
-     * be processed.
+     * Wait for any pending asynchronous opeations (such as copies to a RS
+     * allocation or RS script executions) to complete.
      *
      */
     public void finish() {
@@ -1205,8 +1207,9 @@ public class RenderScript {
     }
 
     /**
-     * Destroy this renderscript context.  Once this function is called its no
-     * longer legal to use this or any objects created by this context.
+     * Destroys this RenderScript context.  Once this function is called,
+     * using this context or any objects belonging to this context is
+     * illegal.
      *
      */
     public void destroy() {