am 379641a7: am ea45ab6f: Merge "Improve RS documentation." into jb-mr2-dev

* commit '379641a7ef09e1d7fab34d3027c5809fb2bc21ad':
  Improve RS documentation.

53 files changed, 519 insertions, 504 deletions

diff --git a/graphics/java/android/renderscript/Allocation.java b/graphics/java/android/renderscript/Allocation.java
index e1b8c6c..362b586 100644
--- a/graphics/java/android/renderscript/Allocation.java
+++ b/graphics/java/android/renderscript/Allocation.java
@@ -31,46 +31,29 @@ import android.graphics.Canvas;
 import android.os.Trace;
 
 /**
- * <p>
- * Memory allocation class for renderscript.  An allocation combines a
- * {@link android.renderscript.Type} with the memory to provide storage for user data and objects.
- * This implies that all memory in Renderscript is typed.
- * </p>
+ * <p> This class provides the primary method through which data is passed to
+ * and from RenderScript kernels.  An Allocation provides the backing store for
+ * a given {@link android.renderscript.Type}.  </p>
  *
- * <p>Allocations are the primary way data moves into and out of scripts. Memory is user
- * synchronized and it's possible for allocations to exist in multiple memory spaces
- * concurrently. Currently those spaces are:</p>
- * <ul>
- * <li>Script: accessable by RS scripts.</li>
- * <li>Graphics Texture: accessable as a graphics texture.</li>
- * <li>Graphics Vertex: accessable as graphical vertex data.</li>
- * <li>Graphics Constants: Accessable as constants in user shaders</li>
- * </ul>
- * </p>
- * <p>
- * For example, when creating a allocation for a texture, the user can
- * specify its memory spaces as both script and textures. This means that it can both
- * be used as script binding and as a GPU texture for rendering. To maintain
- * synchronization if a script modifies an allocation used by other targets it must
- * call a synchronizing function to push the updates to the memory, otherwise the results
- * are undefined.
- * </p>
- * <p>By default, Android system side updates are always applied to the script accessable
- * memory. If this is not present, they are then applied to the various HW
- * memory types.  A {@link android.renderscript.Allocation#syncAll syncAll()}
- * call is necessary after the script data is updated to
- * keep the other memory spaces in sync.</p>
+ * <p>An Allocation also contains a set of usage flags that denote how the
+ * Allocation could be used. For example, an Allocation may have usage flags
+ * specifying that it can be used from a script as well as input to a {@link
+ * android.renderscript.Sampler}. A developer must synchronize across these
+ * different usages using {@link android.renderscript.Allocation#syncAll} in
+ * order to ensure that different users of the Allocation have a consistent view
+ * of memory. For example, in the case where an Allocation is used as the output
+ * of one kernel and as Sampler input in a later kernel, a developer must call
+ * {@link #syncAll syncAll(Allocation.USAGE_SCRIPT)} prior to launching the
+ * second kernel to ensure correctness.
  *
- * <p>Allocation data is uploaded in one of two primary ways. For simple
- * arrays there are copyFrom() functions that take an array from the control code and
- * copy it to the slave memory store. Both type checked and unchecked copies are provided.
- * The unchecked variants exist to allow apps to copy over arrays of structures from a
- * control language that does not support structures.</p>
+ * <p>An Allocation can be populated with the {@link #copyFrom} routines. For
+ * more complex Element types, the {@link #copyFromUnchecked} methods can be
+ * used to copy from byte arrays or similar constructs.</p>
  *
  * <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 Allocation extends BaseObj {
@@ -98,97 +81,102 @@ public class Allocation extends BaseObj {
             new HashMap<Integer, Allocation>();
     IoInputNotifier mBufferNotifier;
 
-
     /**
-     * The usage of the allocation.  These signal to renderscript
-     * where to place the allocation in memory.
+     * The usage of the Allocation.  These signal to RenderScript where to place
+     * the Allocation in memory.
      *
-     * SCRIPT The allocation will be bound to and accessed by
-     * scripts.
+     */
+
+    /**
+     * The Allocation will be bound to and accessed by scripts.
      */
     public static final int USAGE_SCRIPT = 0x0001;
 
     /**
-     * GRAPHICS_TEXTURE The allocation will be used as a texture
-     * source by one or more graphics programs.
+     * The Allocation will be used as a texture source by one or more graphics
+     * programs.
      *
      */
     public static final int USAGE_GRAPHICS_TEXTURE = 0x0002;
 
     /**
-     * GRAPHICS_VERTEX The allocation will be used as a graphics
-     * mesh.
+     * The Allocation will be used as a graphics mesh.
+     *
+     * This was deprecated in API level 16.
      *
      */
     public static final int USAGE_GRAPHICS_VERTEX = 0x0004;
 
 
     /**
-     * GRAPHICS_CONSTANTS The allocation will be used as the source
-     * of shader constants by one or more programs.
+     * The Allocation will be used as the source of shader constants by one or
+     * more programs.
+     *
+     * This was deprecated in API level 16.
      *
      */
     public static final int USAGE_GRAPHICS_CONSTANTS = 0x0008;
 
     /**
-     * USAGE_GRAPHICS_RENDER_TARGET The allocation will be used as a
-     * target for offscreen rendering
+     * The Allocation will be used as a target for offscreen rendering
+     *
+     * This was deprecated in API level 16.
      *
      */
     public static final int USAGE_GRAPHICS_RENDER_TARGET = 0x0010;
 
     /**
-     * USAGE_IO_INPUT The allocation will be used as SurfaceTexture
-     * consumer.  This usage will cause the allocation to be created
-     * read only.
+     * The Allocation will be used as a {@link android.graphics.SurfaceTexture}
+     * consumer.  This usage will cause the Allocation to be created as
+     * read-only.
      *
      */
     public static final int USAGE_IO_INPUT = 0x0020;
 
     /**
-     * USAGE_IO_OUTPUT The allocation will be used as a
-     * SurfaceTexture producer.  The dimensions and format of the
-     * SurfaceTexture will be forced to those of the allocation.
+     * The Allocation will be used as a {@link android.graphics.SurfaceTexture}
+     * producer.  The dimensions and format of the {@link
+     * android.graphics.SurfaceTexture} will be forced to those of the
+     * Allocation.
      *
      */
     public static final int USAGE_IO_OUTPUT = 0x0040;
 
     /**
-     * USAGE_SHARED The allocation's backing store will be inherited
-     * from another object (usually a Bitmap); calling appropriate
-     * copy methods will be significantly faster than if the entire
-     * allocation were copied every time.
+     * The Allocation's backing store will be inherited from another object
+     * (usually a {@link android.graphics.Bitmap}); copying to or from the
+     * original source Bitmap will cause a synchronization rather than a full
+     * copy.  {@link #syncAll} may also be used to synchronize the Allocation
+     * and the source Bitmap.
      *
-     * This is set by default for allocations created with
-     * CreateFromBitmap(RenderScript, Bitmap) in API version 18 and
-     * higher.
+     * <p>This is set by default for allocations created with {@link
+     * #createFromBitmap} in API version 18 and higher.</p>
      *
      */
     public static final int USAGE_SHARED = 0x0080;
 
     /**
-     * Controls mipmap behavior when using the bitmap creation and
-     * update functions.
+     * Controls mipmap behavior when using the bitmap creation and update
+     * functions.
      */
     public enum MipmapControl {
         /**
-         * No mipmaps will be generated and the type generated from the
-         * incoming bitmap will not contain additional LODs.
+         * No mipmaps will be generated and the type generated from the incoming
+         * bitmap will not contain additional LODs.
          */
         MIPMAP_NONE(0),
 
         /**
-         * A Full mipmap chain will be created in script memory.  The
-         * type of the allocation will contain a full mipmap chain.  On
-         * upload to graphics the full chain will be transfered.
+         * A full mipmap chain will be created in script memory.  The Type of
+         * the Allocation will contain a full mipmap chain.  On upload, the full
+         * chain will be transferred.
          */
         MIPMAP_FULL(1),
 
         /**
-         * The type of the allocation will be the same as MIPMAP_NONE.
-         * It will not contain mipmaps.  On upload to graphics the
-         * graphics copy of the allocation data will contain a full
-         * mipmap chain generated from the top level in script memory.
+         * The Type of the Allocation will be the same as MIPMAP_NONE.  It will
+         * not contain mipmaps.  On upload, the allocation data will contain a
+         * full mipmap chain generated from the top level in script memory.
          */
         MIPMAP_ON_SYNC_TO_TEXTURE(2);
 
@@ -208,10 +196,10 @@ public class Allocation extends BaseObj {
 
 
    /**
-     * Get the element of the type of the Allocation.
+     * Get the {@link android.renderscript.Element} of the {@link
+     * android.renderscript.Type} of the Allocation.
      *
-     * @return Element that describes the structure of data in the
-     *         allocation
+     * @return Element
      *
      */
     public Element getElement() {
@@ -221,8 +209,7 @@ public class Allocation extends BaseObj {
     /**
      * Get the usage flags of the Allocation.
      *
-     * @return usage flags associated with the allocation. e.g.
-     *         script, texture, etc.
+     * @return usage this Allocation's set of the USAGE_* flags OR'd together
      *
      */
     public int getUsage() {
@@ -351,7 +338,7 @@ public class Allocation extends BaseObj {
     }
 
     /**
-     * Get the type of the Allocation.
+     * Get the {@link android.renderscript.Type} of the Allocation.
      *
      * @return Type
      *
@@ -361,8 +348,8 @@ public class Allocation extends BaseObj {
     }
 
     /**
-     * Propagate changes from one usage of the allocation to the
-     * remaining usages of the allocation.
+     * Propagate changes from one usage of the Allocation to the
+     * other usages of the Allocation.
      *
      */
     public void syncAll(int srcLocation) {
@@ -391,8 +378,10 @@ public class Allocation extends BaseObj {
     }
 
     /**
-     * Send a buffer to the output stream.  The contents of the
-     * Allocation will be undefined after this operation.
+     * Send a buffer to the output stream.  The contents of the Allocation will
+     * be undefined after this operation. This operation is only valid if {@link
+     * #USAGE_IO_OUTPUT} is set on the Allocation.
+     *
      *
      */
     public void ioSend() {
@@ -415,7 +404,8 @@ public class Allocation extends BaseObj {
     }
 
     /**
-     * Receive the latest input into the Allocation.
+     * Receive the latest input into the Allocation. This operation
+     * is only valid if {@link #USAGE_IO_INPUT} is set on the Allocation.
      *
      */
     public void ioReceive() {
@@ -430,7 +420,7 @@ public class Allocation extends BaseObj {
     }
 
     /**
-     * Copy an array of RS objects to the allocation.
+     * Copy an array of RS objects to the Allocation.
      *
      * @param d Source array.
      */
@@ -506,9 +496,9 @@ public class Allocation extends BaseObj {
     }
 
     /**
-     * Copy an allocation from an array.  This variant is not type
-     * checked which allows an application to fill in structured
-     * data from an array.
+     * Copy into this Allocation from an array. This method does not guarantee
+     * that the Allocation is compatible with the input buffer; it copies memory
+     * without reinterpretation.
      *
      * @param d the source data array
      */
@@ -526,9 +516,9 @@ public class Allocation extends BaseObj {
     }
 
     /**
-     * Copy an allocation from an array.  This variant is not type
-     * checked which allows an application to fill in structured
-     * data from an array.
+     * Copy into this Allocation from an array. This method does not guarantee
+     * that the Allocation is compatible with the input buffer; it copies memory
+     * without reinterpretation.
      *
      * @param d the source data array
      */
@@ -546,9 +536,9 @@ public class Allocation extends BaseObj {
     }
 
     /**
-     * Copy an allocation from an array.  This variant is not type
-     * checked which allows an application to fill in structured
-     * data from an array.
+     * Copy into this Allocation from an array. This method does not guarantee
+     * that the Allocation is compatible with the input buffer; it copies memory
+     * without reinterpretation.
      *
      * @param d the source data array
      */
@@ -566,9 +556,9 @@ public class Allocation extends BaseObj {
     }
 
     /**
-     * Copy an allocation from an array.  This variant is not type
-     * checked which allows an application to fill in structured
-     * data from an array.
+     * Copy into this Allocation from an array. This method does not guarantee
+     * that the Allocation is compatible with the input buffer; it copies memory
+     * without reinterpretation.
      *
      * @param d the source data array
      */
@@ -587,9 +577,9 @@ public class Allocation extends BaseObj {
 
 
     /**
-     * Copy an allocation from an array.  This variant is type
-     * checked and will generate exceptions if the Allocation type
-     * is not a 32 bit integer type.
+     * Copy into this Allocation from an array.  This variant is type checked
+     * and will generate exceptions if the Allocation's {@link
+     * android.renderscript.Element} is not a 32 bit integer type.
      *
      * @param d the source data array
      */
@@ -607,9 +597,9 @@ public class Allocation extends BaseObj {
     }
 
     /**
-     * Copy an allocation from an array.  This variant is type
-     * checked and will generate exceptions if the Allocation type
-     * is not a 16 bit integer type.
+     * Copy into this Allocation from an array.  This variant is type checked
+     * and will generate exceptions if the Allocation's {@link
+     * android.renderscript.Element} is not a 16 bit integer type.
      *
      * @param d the source data array
      */
@@ -627,9 +617,9 @@ public class Allocation extends BaseObj {
     }
 
     /**
-     * Copy an allocation from an array.  This variant is type
-     * checked and will generate exceptions if the Allocation type
-     * is not a 8 bit integer type.
+     * Copy into this Allocation from an array.  This variant is type checked
+     * and will generate exceptions if the Allocation's {@link
+     * android.renderscript.Element} is not an 8 bit integer type.
      *
      * @param d the source data array
      */
@@ -647,9 +637,9 @@ public class Allocation extends BaseObj {
     }
 
     /**
-     * Copy an allocation from an array.  This variant is type
-     * checked and will generate exceptions if the Allocation type
-     * is not a 32 bit float type.
+     * Copy into this Allocation from an array.  This variant is type checked
+     * and will generate exceptions if the Allocation's {@link
+     * android.renderscript.Element} is not a 32 bit float type.
      *
      * @param d the source data array
      */
@@ -667,8 +657,15 @@ public class Allocation extends BaseObj {
     }
 
     /**
-     * Copy an allocation from a bitmap.  The height, width, and
-     * format of the bitmap must match the existing allocation.
+     * Copy into an Allocation from a {@link android.graphics.Bitmap}.  The
+     * height, width, and format of the bitmap must match the existing
+     * allocation.
+     *
+     * <p>If the {@link android.graphics.Bitmap} is the same as the {@link
+     * android.graphics.Bitmap} used to create the Allocation with {@link
+     * #createFromBitmap} and {@link #USAGE_SHARED} is set on the Allocation,
+     * this will synchronize the Allocation with the latest data from the {@link
+     * android.graphics.Bitmap}, potentially avoiding the actual copy.</p>
      *
      * @param b the source bitmap
      */
@@ -689,7 +686,7 @@ public class Allocation extends BaseObj {
     }
 
     /**
-     * Copy an allocation from an allocation.  The types of both allocations
+     * Copy an Allocation from an Allocation.  The types of both allocations
      * must be identical.
      *
      * @param a the source allocation
@@ -705,8 +702,8 @@ public class Allocation extends BaseObj {
     }
 
     /**
-     * This is only intended to be used by auto-generate code reflected from the
-     * renderscript script files.
+     * This is only intended to be used by auto-generated code reflected from
+     * the RenderScript script files and should not be used by developers.
      *
      * @param xoff
      * @param fp
@@ -725,8 +722,8 @@ public class Allocation extends BaseObj {
     }
 
     /**
-     * This is only intended to be used by auto-generate code reflected from the
-     * renderscript script files.
+     * This is only intended to be used by auto-generated code reflected from
+     * the RenderScript script files.
      *
      * @param xoff
      * @param component_number
@@ -772,23 +769,22 @@ public class Allocation extends BaseObj {
     }
 
     /**
-     * Generate a mipmap chain.  Requires the type of the allocation
-     * include mipmaps.
+     * Generate a mipmap chain. This is only valid if the Type of the Allocation
+     * includes mipmaps.
      *
-     * This function will generate a complete set of mipmaps from
-     * the top level lod and place them into the script memoryspace.
+     * <p>This function will generate a complete set of mipmaps from the top
+     * level LOD and place them into the script memory space.</p>
      *
-     * If the allocation is also using other memory spaces a
-     * followup sync will be required.
+     * <p>If the Allocation is also using other memory spaces, a call to {@link
+     * #syncAll syncAll(Allocation.USAGE_SCRIPT)} is required.</p>
      */
     public void generateMipmaps() {
         mRS.nAllocationGenerateMipmaps(getID(mRS));
     }
 
     /**
-     * Copy part of an allocation from an array.  This variant is
-     * not type checked which allows an application to fill in
-     * structured data from an array.
+     * Copy an array into part of this Allocation.  This method does not
+     * guarantee that the Allocation is compatible with the input buffer.
      *
      * @param off The offset of the first element to be copied.
      * @param count The number of elements to be copied.
@@ -803,9 +799,8 @@ public class Allocation extends BaseObj {
     }
 
     /**
-     * Copy part of an allocation from an array.  This variant is
-     * not type checked which allows an application to fill in
-     * structured data from an array.
+     * Copy an array into part of this Allocation.  This method does not
+     * guarantee that the Allocation is compatible with the input buffer.
      *
      * @param off The offset of the first element to be copied.
      * @param count The number of elements to be copied.
@@ -820,9 +815,8 @@ public class Allocation extends BaseObj {
     }
 
     /**
-     * Copy part of an allocation from an array.  This variant is
-     * not type checked which allows an application to fill in
-     * structured data from an array.
+     * Copy an array into part of this Allocation.  This method does not
+     * guarantee that the Allocation is compatible with the input buffer.
      *
      * @param off The offset of the first element to be copied.
      * @param count The number of elements to be copied.
@@ -837,9 +831,8 @@ public class Allocation extends BaseObj {
     }
 
     /**
-     * Copy part of an allocation from an array.  This variant is
-     * not type checked which allows an application to fill in
-     * structured data from an array.
+     * Copy an array into part of this Allocation.  This method does not
+     * guarantee that the Allocation is compatible with the input buffer.
      *
      * @param off The offset of the first element to be copied.
      * @param count The number of elements to be copied.
@@ -854,9 +847,9 @@ public class Allocation extends BaseObj {
     }
 
     /**
-     * Copy part of an allocation from an array.  This variant is
-     * type checked and will generate exceptions if the Allocation
-     * type is not a 32 bit integer type.
+     * Copy an array into part of this Allocation.  This variant is type checked
+     * and will generate exceptions if the Allocation type is not a 32 bit
+     * integer type.
      *
      * @param off The offset of the first element to be copied.
      * @param count The number of elements to be copied.
@@ -870,9 +863,9 @@ public class Allocation extends BaseObj {
     }
 
     /**
-     * Copy part of an allocation from an array.  This variant is
-     * type checked and will generate exceptions if the Allocation
-     * type is not a 16 bit integer type.
+     * Copy an array into part of this Allocation.  This variant is type checked
+     * and will generate exceptions if the Allocation type is not a 16 bit
+     * integer type.
      *
      * @param off The offset of the first element to be copied.
      * @param count The number of elements to be copied.
@@ -886,9 +879,9 @@ public class Allocation extends BaseObj {
     }
 
     /**
-     * Copy part of an allocation from an array.  This variant is
-     * type checked and will generate exceptions if the Allocation
-     * type is not a 8 bit integer type.
+     * Copy an array into part of this Allocation.  This variant is type checked
+     * and will generate exceptions if the Allocation type is not an 8 bit
+     * integer type.
      *
      * @param off The offset of the first element to be copied.
      * @param count The number of elements to be copied.
@@ -902,9 +895,9 @@ public class Allocation extends BaseObj {
     }
 
     /**
-     * Copy part of an allocation from an array.  This variant is
-     * type checked and will generate exceptions if the Allocation
-     * type is not a 32 bit float type.
+     * Copy an array into part of this Allocation.  This variant is type checked
+     * and will generate exceptions if the Allocation type is not a 32 bit float
+     * type.
      *
      * @param off The offset of the first element to be copied.
      * @param count The number of elements to be copied.
@@ -917,7 +910,7 @@ public class Allocation extends BaseObj {
         Trace.traceEnd(RenderScript.TRACE_TAG);
     }
      /**
-     * Copy part of an allocation from another allocation.
+     * Copy part of an Allocation into this Allocation.
      *
      * @param off The offset of the first element to be copied.
      * @param count The number of elements to be copied.
@@ -987,14 +980,14 @@ public class Allocation extends BaseObj {
     }
 
     /**
-     * Copy a rectangular region from the array into the allocation.
-     * The incoming array is assumed to be tightly packed.
+     * Copy from an array into a rectangular region in this Allocation.  The
+     * array is assumed to be tightly packed.
      *
-     * @param xoff X offset of the region to update
-     * @param yoff Y offset of the region to update
-     * @param w Width of the incoming region to update
-     * @param h Height of the incoming region to update
-     * @param data to be placed into the allocation
+     * @param xoff X offset of the region to update in this Allocation
+     * @param yoff Y offset of the region to update in this Allocation
+     * @param w Width of the region to update
+     * @param h Height of the region to update
+     * @param data to be placed into the Allocation
      */
     public void copy2DRangeFrom(int xoff, int yoff, int w, int h, byte[] data) {
         Trace.traceBegin(RenderScript.TRACE_TAG, "copy2DRangeFrom");
@@ -1003,6 +996,16 @@ public class Allocation extends BaseObj {
         Trace.traceEnd(RenderScript.TRACE_TAG);
     }
 
+    /**
+     * Copy from an array into a rectangular region in this Allocation.  The
+     * array is assumed to be tightly packed.
+     *
+     * @param xoff X offset of the region to update in this Allocation
+     * @param yoff Y offset of the region to update in this Allocation
+     * @param w Width of the region to update
+     * @param h Height of the region to update
+     * @param data to be placed into the Allocation
+     */
     public void copy2DRangeFrom(int xoff, int yoff, int w, int h, short[] data) {
         Trace.traceBegin(RenderScript.TRACE_TAG, "copy2DRangeFrom");
         validateIsInt16();
@@ -1010,6 +1013,16 @@ public class Allocation extends BaseObj {
         Trace.traceEnd(RenderScript.TRACE_TAG);
     }
 
+    /**
+     * Copy from an array into a rectangular region in this Allocation.  The
+     * array is assumed to be tightly packed.
+     *
+     * @param xoff X offset of the region to update in this Allocation
+     * @param yoff Y offset of the region to update in this Allocation
+     * @param w Width of the region to update
+     * @param h Height of the region to update
+     * @param data to be placed into the Allocation
+     */
     public void copy2DRangeFrom(int xoff, int yoff, int w, int h, int[] data) {
         Trace.traceBegin(RenderScript.TRACE_TAG, "copy2DRangeFrom");
         validateIsInt32();
@@ -1017,6 +1030,16 @@ public class Allocation extends BaseObj {
         Trace.traceEnd(RenderScript.TRACE_TAG);
     }
 
+    /**
+     * Copy from an array into a rectangular region in this Allocation.  The
+     * array is assumed to be tightly packed.
+     *
+     * @param xoff X offset of the region to update in this Allocation
+     * @param yoff Y offset of the region to update in this Allocation
+     * @param w Width of the region to update
+     * @param h Height of the region to update
+     * @param data to be placed into the Allocation
+     */
     public void copy2DRangeFrom(int xoff, int yoff, int w, int h, float[] data) {
         Trace.traceBegin(RenderScript.TRACE_TAG, "copy2DRangeFrom");
         validateIsFloat32();
@@ -1025,16 +1048,16 @@ public class Allocation extends BaseObj {
     }
 
     /**
-     * Copy a rectangular region into the allocation from another
-     * allocation.
+     * Copy a rectangular region from an Allocation into a rectangular region in
+     * this Allocation.
      *
-     * @param xoff X offset of the region to update.
-     * @param yoff Y offset of the region to update.
-     * @param w Width of the incoming region to update.
-     * @param h Height of the incoming region to update.
-     * @param data source allocation.
-     * @param dataXoff X offset in data of the region to update.
-     * @param dataYoff Y offset in data of the region to update.
+     * @param xoff X offset of the region in this Allocation
+     * @param yoff Y offset of the region in this Allocation
+     * @param w Width of the region to update.
+     * @param h Height of the region to update.
+     * @param data source Allocation.
+     * @param dataXoff X offset in source Allocation
+     * @param dataYoff Y offset in source Allocation
      */
     public void copy2DRangeFrom(int xoff, int yoff, int w, int h,
                                 Allocation data, int dataXoff, int dataYoff) {
@@ -1049,13 +1072,13 @@ public class Allocation extends BaseObj {
     }
 
     /**
-     * Copy a bitmap into an allocation.  The height and width of
-     * the update will use the height and width of the incoming
-     * bitmap.
+     * Copy a {@link android.graphics.Bitmap} into an Allocation.  The height
+     * and width of the update will use the height and width of the {@link
+     * android.graphics.Bitmap}.
      *
-     * @param xoff X offset of the region to update
-     * @param yoff Y offset of the region to update
-     * @param data the bitmap to be copied
+     * @param xoff X offset of the region to update in this Allocation
+     * @param yoff Y offset of the region to update in this Allocation
+     * @param data the Bitmap to be copied
      */
     public void copy2DRangeFrom(int xoff, int yoff, Bitmap data) {
         Trace.traceBegin(RenderScript.TRACE_TAG, "copy2DRangeFrom");
@@ -1138,14 +1161,14 @@ public class Allocation extends BaseObj {
     /**
      * @hide
      * Copy a rectangular region from the array into the allocation.
-     * The incoming array is assumed to be tightly packed.
-     *
-     * @param xoff X offset of the region to update
-     * @param yoff Y offset of the region to update
-     * @param zoff Z offset of the region to update
-     * @param w Width of the incoming region to update
-     * @param h Height of the incoming region to update
-     * @param d Depth of the incoming region to update
+     * The array is assumed to be tightly packed.
+     *
+     * @param xoff X offset of the region to update in this Allocation
+     * @param yoff Y offset of the region to update in this Allocation
+     * @param zoff Z offset of the region to update in this Allocation
+     * @param w Width of the region to update
+     * @param h Height of the region to update
+     * @param d Depth of the region to update
      * @param data to be placed into the allocation
      */
     public void copy3DRangeFrom(int xoff, int yoff, int zoff, int w, int h, int d, byte[] data) {
@@ -1185,15 +1208,16 @@ public class Allocation extends BaseObj {
      * Copy a rectangular region into the allocation from another
      * allocation.
      *
-     * @param xoff X offset of the region to update.
-     * @param yoff Y offset of the region to update.
-     * @param w Width of the incoming region to update.
-     * @param h Height of the incoming region to update.
-     * @param d Depth of the incoming region to update.
+     * @param xoff X offset of the region to update in this Allocation
+     * @param yoff Y offset of the region to update in this Allocation
+     * @param zoff Z offset of the region to update in this Allocation
+     * @param w Width of the region to update.
+     * @param h Height of the region to update.
+     * @param d Depth of the region to update.
      * @param data source allocation.
-     * @param dataXoff X offset in data of the region to update.
-     * @param dataYoff Y offset in data of the region to update.
-     * @param dataZoff Z offset in data of the region to update
+     * @param dataXoff X offset of the region in the source Allocation
+     * @param dataYoff Y offset of the region in the source Allocation
+     * @param dataZoff Z offset of the region in the source Allocation
      */
     public void copy3DRangeFrom(int xoff, int yoff, int zoff, int w, int h, int d,
                                 Allocation data, int dataXoff, int dataYoff, int dataZoff) {
@@ -1206,8 +1230,8 @@ public class Allocation extends BaseObj {
 
 
     /**
-     * Copy from the Allocation into a Bitmap.  The bitmap must
-     * match the dimensions of the Allocation.
+     * Copy from the Allocation into a {@link android.graphics.Bitmap}.  The
+     * bitmap must match the dimensions of the Allocation.
      *
      * @param b The bitmap to be set from the Allocation.
      */
@@ -1221,9 +1245,9 @@ public class Allocation extends BaseObj {
     }
 
     /**
-     * Copy from the Allocation into a byte array.  The array must
-     * be at least as large as the Allocation.  The allocation must
-     * be of an 8 bit elemental type.
+     * Copy from the Allocation into a byte array.  The array must be at least
+     * as large as the Allocation.  The allocation must be of an 8 bit integer
+     * {@link android.renderscript.Element} type.
      *
      * @param d The array to be set from the Allocation.
      */
@@ -1236,9 +1260,9 @@ public class Allocation extends BaseObj {
     }
 
     /**
-     * Copy from the Allocation into a short array.  The array must
-     * be at least as large as the Allocation.  The allocation must
-     * be of an 16 bit elemental type.
+     * Copy from the Allocation into a short array.  The array must be at least
+     * as large as the Allocation.  The allocation must be of an 16 bit integer
+     * {@link android.renderscript.Element} type.
      *
      * @param d The array to be set from the Allocation.
      */
@@ -1251,9 +1275,9 @@ public class Allocation extends BaseObj {
     }
 
     /**
-     * Copy from the Allocation into a int array.  The array must be
-     * at least as large as the Allocation.  The allocation must be
-     * of an 32 bit elemental type.
+     * Copy from the Allocation into a int array.  The array must be at least as
+     * large as the Allocation.  The allocation must be of an 32 bit integer
+     * {@link android.renderscript.Element} type.
      *
      * @param d The array to be set from the Allocation.
      */
@@ -1266,9 +1290,9 @@ public class Allocation extends BaseObj {
     }
 
     /**
-     * Copy from the Allocation into a float array.  The array must
-     * be at least as large as the Allocation.  The allocation must
-     * be of an 32 bit float elemental type.
+     * Copy from the Allocation into a float array.  The array must be at least
+     * as large as the Allocation.  The allocation must be of an 32 bit float
+     * {@link android.renderscript.Element} type.
      *
      * @param d The array to be set from the Allocation.
      */
@@ -1281,20 +1305,19 @@ public class Allocation extends BaseObj {
     }
 
     /**
-     * Resize a 1D allocation.  The contents of the allocation are
-     * preserved.  If new elements are allocated objects are created
-     * with null contents and the new region is otherwise undefined.
+     * Resize a 1D allocation.  The contents of the allocation are preserved.
+     * If new elements are allocated objects are created with null contents and
+     * the new region is otherwise undefined.
      *
-     * If the new region is smaller the references of any objects
-     * outside the new region will be released.
+     * <p>If the new region is smaller the references of any objects outside the
+     * new region will be released.</p>
      *
-     * A new type will be created with the new dimension.
+     * <p>A new type will be created with the new dimension.</p>
      *
      * @param dimX The new size of the allocation.
      *
-     * @deprecated Renderscript objects should be immutable once
-     * created.  The replacement is to create a new allocation and copy the
-     * contents.
+     * @deprecated RenderScript objects should be immutable once created.  The
+     * replacement is to create a new allocation and copy the contents.
      */
     public synchronized void resize(int dimX) {
         if ((mType.getY() > 0)|| (mType.getZ() > 0) || mType.hasFaces() || mType.hasMipmaps()) {
@@ -1318,11 +1341,13 @@ public class Allocation extends BaseObj {
     }
 
     /**
+     * Creates a new Allocation with the given {@link
+     * android.renderscript.Type}, mipmap flag, and usage flags.
      *
-     * @param type renderscript type describing data layout
+     * @param type RenderScript type describing data layout
      * @param mips specifies desired mipmap behaviour for the
      *             allocation
-     * @param usage bit field specifying how the allocation is
+     * @param usage bit field specifying how the Allocation is
      *              utilized
      */
     static public Allocation createTyped(RenderScript rs, Type type, MipmapControl mips, int usage) {
@@ -1340,8 +1365,8 @@ public class Allocation extends BaseObj {
     }
 
     /**
-     * Creates a renderscript allocation with the size specified by
-     * the type and no mipmaps generated by default
+     * Creates an Allocation with the size specified by the type and no mipmaps
+     * generated by default
      *
      * @param rs Context to which the allocation will belong.
      * @param type renderscript type describing data layout
@@ -1355,12 +1380,11 @@ public class Allocation extends BaseObj {
     }
 
     /**
-     * Creates a renderscript allocation for use by the script with
-     * the size specified by the type and no mipmaps generated by
-     * default
+     * Creates an Allocation for use by scripts with a given {@link
+     * android.renderscript.Type} and no mipmaps
      *
-     * @param rs Context to which the allocation will belong.
-     * @param type renderscript type describing data layout
+     * @param rs Context to which the Allocation will belong.
+     * @param type RenderScript Type describing data layout
      *
      * @return allocation
      */
@@ -1369,13 +1393,12 @@ public class Allocation extends BaseObj {
     }
 
     /**
-     * Creates a renderscript allocation with a specified number of
-     * given elements
+     * Creates an Allocation with a specified number of given elements
      *
-     * @param rs Context to which the allocation will belong.
-     * @param e describes what each element of an allocation is
-     * @param count specifies the number of element in the allocation
-     * @param usage bit field specifying how the allocation is
+     * @param rs Context to which the Allocation will belong.
+     * @param e Element to use in the Allocation
+     * @param count the number of Elements in the Allocation
+     * @param usage bit field specifying how the Allocation is
      *              utilized
      *
      * @return allocation
@@ -1397,12 +1420,11 @@ public class Allocation extends BaseObj {
     }
 
     /**
-     * Creates a renderscript allocation with a specified number of
-     * given elements
+     * Creates an Allocation with a specified number of given elements
      *
-     * @param rs Context to which the allocation will belong.
-     * @param e describes what each element of an allocation is
-     * @param count specifies the number of element in the allocation
+     * @param rs Context to which the Allocation will belong.
+     * @param e Element to use in the Allocation
+     * @param count the number of Elements in the Allocation
      *
      * @return allocation
      */
@@ -1438,16 +1460,16 @@ public class Allocation extends BaseObj {
     }
 
     /**
-     * Creates a renderscript allocation from a bitmap
+     * Creates an Allocation from a {@link android.graphics.Bitmap}.
      *
      * @param rs Context to which the allocation will belong.
-     * @param b bitmap source for the allocation data
+     * @param b Bitmap source for the allocation data
      * @param mips specifies desired mipmap behaviour for the
      *             allocation
      * @param usage bit field specifying how the allocation is
      *              utilized
      *
-     * @return renderscript allocation containing bitmap data
+     * @return Allocation containing bitmap data
      *
      */
     static public Allocation createFromBitmap(RenderScript rs, Bitmap b,
@@ -1494,9 +1516,9 @@ public class Allocation extends BaseObj {
     }
 
     /**
-     * For allocations used with io operations, returns the handle
-     * onto a raw buffer that is being managed by the screen
-     * compositor.
+     * Returns the handle to a raw buffer that is being managed by the screen
+     * compositor. This operation is only valid for Allocations with {@link
+     * #USAGE_IO_INPUT}.
      *
      * @return Surface object associated with allocation
      *
@@ -1516,7 +1538,8 @@ public class Allocation extends BaseObj {
     }
 
     /**
-     * Associate a surface for io output with this allocation
+     * Associate a {@link android.view.Surface} with this Allocation. This
+     * operation is only valid for Allocations with {@link #USAGE_IO_OUTPUT}.
      *
      * @param sur Surface to associate with allocation
      */
@@ -1530,16 +1553,17 @@ public class Allocation extends BaseObj {
     }
 
     /**
-     * Creates a RenderScript allocation from a bitmap.
+     * Creates an Allocation from a {@link android.graphics.Bitmap}.
      *
-     * With target API version 18 or greater, this allocation will be
-     * created with USAGE_SHARED. With target API version 17 or lower,
-     * this allocation will be created with USAGE_GRAPHICS_TEXTURE.
+     * <p>With target API version 18 or greater, this Allocation will be created
+     * with {@link #USAGE_SHARED}, {@link #USAGE_SCRIPT}, and {@link
+     * #USAGE_GRAPHICS_TEXTURE}. With target API version 17 or lower, this
+     * Allocation will be created with {@link #USAGE_GRAPHICS_TEXTURE}.</p>
      *
      * @param rs Context to which the allocation will belong.
      * @param b bitmap source for the allocation data
      *
-     * @return renderscript allocation containing bitmap data
+     * @return Allocation containing bitmap data
      *
      */
     static public Allocation createFromBitmap(RenderScript rs, Bitmap b) {
@@ -1552,12 +1576,13 @@ public class Allocation extends BaseObj {
     }
 
     /**
-     * Creates a cubemap allocation from a bitmap containing the
-     * horizontal list of cube faces. Each individual face must be
-     * the same size and power of 2
+     * Creates a cubemap Allocation from a {@link android.graphics.Bitmap}
+     * containing the horizontal list of cube faces. Each face must be a square,
+     * have the same size as all other faces, and have a width that is a power
+     * of 2.
      *
      * @param rs Context to which the allocation will belong.
-     * @param b bitmap with cubemap faces layed out in the following
+     * @param b Bitmap with cubemap faces layed out in the following
      *          format: right, left, top, bottom, front, back
      * @param mips specifies desired mipmap behaviour for the cubemap
      * @param usage bit field specifying how the cubemap is utilized
@@ -1600,10 +1625,10 @@ public class Allocation extends BaseObj {
     }
 
     /**
-     * Creates a non-mipmapped cubemap allocation for use as a
-     * graphics texture from a bitmap containing the horizontal list
-     * of cube faces. Each individual face must be the same size and
-     * power of 2
+     * Creates a non-mipmapped cubemap Allocation for use as a graphics texture
+     * from a {@link android.graphics.Bitmap} containing the horizontal list of
+     * cube faces. Each face must be a square, have the same size as all other
+     * faces, and have a width that is a power of 2.
      *
      * @param rs Context to which the allocation will belong.
      * @param b bitmap with cubemap faces layed out in the following
@@ -1619,9 +1644,9 @@ public class Allocation extends BaseObj {
     }
 
     /**
-     * Creates a cubemap allocation from 6 bitmaps containing
-     * the cube faces. All the faces must be the same size and
-     * power of 2
+     * Creates a cubemap Allocation from 6 {@link android.graphics.Bitmap}
+     * objects containing the cube faces. Each face must be a square, have the
+     * same size as all other faces, and have a width that is a power of 2.
      *
      * @param rs Context to which the allocation will belong.
      * @param xpos cubemap face in the positive x direction
@@ -1686,10 +1711,10 @@ public class Allocation extends BaseObj {
     }
 
     /**
-     * Creates a non-mipmapped cubemap allocation for use as a
-     * graphics texture from 6 bitmaps containing
-     * the cube faces. All the faces must be the same size and
-     * power of 2
+     * Creates a non-mipmapped cubemap Allocation for use as a sampler input
+     * from 6 {@link android.graphics.Bitmap} objects containing the cube
+     * faces. Each face must be a square, have the same size as all other faces,
+     * and have a width that is a power of 2.
      *
      * @param rs Context to which the allocation will belong.
      * @param xpos cubemap face in the positive x direction
@@ -1715,8 +1740,8 @@ public class Allocation extends BaseObj {
     }
 
     /**
-     * Creates a renderscript allocation from the bitmap referenced
-     * by resource id
+     * Creates an Allocation from the Bitmap referenced
+     * by resource ID.
      *
      * @param rs Context to which the allocation will belong.
      * @param res application resources
@@ -1726,7 +1751,7 @@ public class Allocation extends BaseObj {
      * @param usage bit field specifying how the allocation is
      *              utilized
      *
-     * @return renderscript allocation containing resource data
+     * @return Allocation containing resource data
      *
      */
     static public Allocation createFromBitmapResource(RenderScript rs,
@@ -1746,18 +1771,19 @@ public class Allocation extends BaseObj {
     }
 
     /**
-     * Creates a non-mipmapped renderscript allocation to use as a
-     * graphics texture from the bitmap referenced by resource id
+     * Creates a non-mipmapped Allocation to use as a graphics texture from the
+     * {@link android.graphics.Bitmap} referenced by resource ID.
      *
-     * With target API version 18 or greater, this allocation will be
-     * created with USAGE_SHARED. With target API version 17 or lower,
-     * this allocation will be created with USAGE_GRAPHICS_TEXTURE.
+     * <p>With target API version 18 or greater, this allocation will be created
+     * with {@link #USAGE_SCRIPT} and {@link #USAGE_GRAPHICS_TEXTURE}. With
+     * target API version 17 or lower, this allocation will be created with
+     * {@link #USAGE_GRAPHICS_TEXTURE}.</p>
      *
      * @param rs Context to which the allocation will belong.
      * @param res application resources
      * @param id resource id to load the data from
      *
-     * @return renderscript allocation containing resource data
+     * @return Allocation containing resource data
      *
      */
     static public Allocation createFromBitmapResource(RenderScript rs,
@@ -1774,8 +1800,7 @@ public class Allocation extends BaseObj {
     }
 
     /**
-     * Creates a renderscript allocation containing string data
-     * encoded in UTF-8 format
+     * Creates an Allocation containing string data encoded in UTF-8 format.
      *
      * @param rs Context to which the allocation will belong.
      * @param str string to create the allocation from
@@ -1802,11 +1827,10 @@ public class Allocation extends BaseObj {
     /**
      * @hide
      *
-     * Interface to handle notification when new buffers are
-     * available via USAGE_IO_INPUT.  An application will receive
-     * one notification when a buffer is available.  Additional
-     * buffers will not trigger new notifications until a buffer is
-     * processed.
+     * Interface to handle notification when new buffers are available via
+     * {@link #USAGE_IO_INPUT}. An application will receive one notification
+     * when a buffer is available. Additional buffers will not trigger new
+     * notifications until a buffer is processed.
      */
     public interface IoInputNotifier {
         public void onBufferAvailable(Allocation a);
@@ -1815,7 +1839,7 @@ public class Allocation extends BaseObj {
     /**
      * @hide
      *
-     * Set a notification handler for USAGE_IO_INPUT
+     * Set a notification handler for {@link #USAGE_IO_INPUT}.
      *
      * @param callback instance of the IoInputNotifier class to be called
      *                 when buffer arrive.
@@ -1839,4 +1863,3 @@ public class Allocation extends BaseObj {
 
 }
 
-
diff --git a/graphics/java/android/renderscript/AllocationAdapter.java b/graphics/java/android/renderscript/AllocationAdapter.java
index 85d86e5..a6645bb 100644
--- a/graphics/java/android/renderscript/AllocationAdapter.java
+++ b/graphics/java/android/renderscript/AllocationAdapter.java
@@ -22,6 +22,7 @@ import android.graphics.BitmapFactory;
 import android.util.TypedValue;
 
 /**
+ * Only intended for use by generated reflected code.
  *
  **/
 public class AllocationAdapter extends Allocation {
diff --git a/graphics/java/android/renderscript/BaseObj.java b/graphics/java/android/renderscript/BaseObj.java
index f464f9b..e17d79a 100644
--- a/graphics/java/android/renderscript/BaseObj.java
+++ b/graphics/java/android/renderscript/BaseObj.java
@@ -19,9 +19,9 @@ package android.renderscript;
 import android.util.Log;
 
 /**
- * BaseObj is the base class for interfacing with native renderscript objects.
- * It primarly contains code for tracking the native object ID and forcably
- * disconecting the object from the native allocation for early cleanup.
+ * BaseObj is the base class for all RenderScript objects owned by a RS context.
+ * It is responsible for lifetime management and resource tracking. This class
+ * should not be used by a user application.
  *
  **/
 public class BaseObj {
@@ -75,8 +75,7 @@ public class BaseObj {
 
     /**
      * setName assigns a name to an object.  This object can later be looked up
-     * by this name.  This name will also be retained if the object is written
-     * to an A3D file.
+     * by this name.
      *
      * @param name The name to assign to the object.
      */
@@ -125,10 +124,9 @@ public class BaseObj {
     }
 
     /**
-     * destroy disconnects the object from the native object effectively
-     * rendering this java object dead.  The primary use is to force immediate
-     * cleanup of resources when it is believed the GC will not respond quickly
-     * enough.
+     * Frees any native resources associated with this object.  The
+     * primary use is to force immediate cleanup of resources when it is
+     * believed the GC will not respond quickly enough.
      */
     synchronized public void destroy() {
         if(mDestroyed) {
diff --git a/graphics/java/android/renderscript/Byte2.java b/graphics/java/android/renderscript/Byte2.java
index 7df5f2e..cf34f3a 100644
--- a/graphics/java/android/renderscript/Byte2.java
+++ b/graphics/java/android/renderscript/Byte2.java
@@ -21,7 +21,7 @@ import android.util.Log;
 
 
 /**
- * Class for exposing the native Renderscript byte2 type back to the Android system.
+ * Class for exposing the native RenderScript byte2 type back to the Android system.
  *
  **/
 public class Byte2 {
diff --git a/graphics/java/android/renderscript/Byte3.java b/graphics/java/android/renderscript/Byte3.java
index 02a01c1..266e94d 100644
--- a/graphics/java/android/renderscript/Byte3.java
+++ b/graphics/java/android/renderscript/Byte3.java
@@ -21,7 +21,7 @@ import android.util.Log;
 
 
 /**
- * Class for exposing the native Renderscript byte3 type back to the Android system.
+ * Class for exposing the native RenderScript byte3 type back to the Android system.
  *
  **/
 public class Byte3 {
diff --git a/graphics/java/android/renderscript/Byte4.java b/graphics/java/android/renderscript/Byte4.java
index a55a696..68c8f52 100644
--- a/graphics/java/android/renderscript/Byte4.java
+++ b/graphics/java/android/renderscript/Byte4.java
@@ -21,7 +21,7 @@ import android.util.Log;
 
 
 /**
- * Class for exposing the native Renderscript byte4 type back to the Android system.
+ * Class for exposing the native RenderScript byte4 type back to the Android system.
  *
  **/
 public class Byte4 {
diff --git a/graphics/java/android/renderscript/Double2.java b/graphics/java/android/renderscript/Double2.java
index 9f4f328..29fd515 100644
--- a/graphics/java/android/renderscript/Double2.java
+++ b/graphics/java/android/renderscript/Double2.java
@@ -21,7 +21,7 @@ import android.util.Log;
 
 
 /**
- * Class for exposing the native Renderscript double2 type back
+ * Class for exposing the native RenderScript double2 type back
  * to the Android system.
  *
  **/
diff --git a/graphics/java/android/renderscript/Double3.java b/graphics/java/android/renderscript/Double3.java
index eb55142..818952e 100644
--- a/graphics/java/android/renderscript/Double3.java
+++ b/graphics/java/android/renderscript/Double3.java
@@ -21,7 +21,7 @@ import android.util.Log;
 
 
 /**
- * Class for exposing the native Renderscript double3 type back
+ * Class for exposing the native RenderScript double3 type back
  * to the Android system.
  *
  **/
diff --git a/graphics/java/android/renderscript/Double4.java b/graphics/java/android/renderscript/Double4.java
index 4755a76..7775ab7 100644
--- a/graphics/java/android/renderscript/Double4.java
+++ b/graphics/java/android/renderscript/Double4.java
@@ -21,7 +21,7 @@ import android.util.Log;
 
 
 /**
- * Class for exposing the native Renderscript double4 type back
+ * Class for exposing the native RenderScript double4 type back
  * to the Android system.
  *
  **/
diff --git a/graphics/java/android/renderscript/Element.java b/graphics/java/android/renderscript/Element.java
index f6c07d1..3838c61 100644
--- a/graphics/java/android/renderscript/Element.java
+++ b/graphics/java/android/renderscript/Element.java
@@ -20,31 +20,37 @@ import java.lang.reflect.Field;
 import android.util.Log;
 
 /**
- * <p>The most basic data type. An element represents one cell of a memory allocation.
- * Element is the basic data type of Renderscript. An element can be of two forms: Basic elements or Complex forms.
- * Examples of basic elements are:</p>
- * <ul>
- *  <li>Single float value</li>
- *  <li>4 element float vector</li>
- *  <li>single RGB-565 color</li>
- *  <li>single unsigned int 16</li>
- * </ul>
- * <p>Complex elements contain a list of sub-elements and names that
- * represents a structure of data. The fields can be accessed by name
- * from a script or shader. The memory layout is defined and ordered. Data
- * alignment is determined by the most basic primitive type. i.e. a float4
- * vector will be aligned to sizeof(float) and not sizeof(float4). The
- * ordering of elements in memory will be the order in which they were added
- * with each component aligned as necessary. No re-ordering will be done.</p>
+ * <p>An Element represents one item within an {@link
+ * android.renderscript.Allocation}.  An Element is roughly equivalent to a C
+ * type in a RenderScript kernel. Elements may be basic or complex. Some basic
+ * elements are</p> <ul> <li>A single float value (equivalent to a float in a
+ * kernel)</li> <li>A four-element float vector (equivalent to a float4 in a
+ * kernel)</li> <li>An unsigned 32-bit integer (equivalent to an unsigned int in
+ * a kernel)</li> <li>A single signed 8-bit integer (equivalent to a char in a
+ * kernel)</li> </ul> <p>A complex element is roughly equivalent to a C struct
+ * and contains a number of basic or complex Elements. From Java code, a complex
+ * element contains a list of sub-elements and names that represents a
+ * particular data structure. Structs used in RS scripts are available to Java
+ * code by using the {@code ScriptField_structname} class that is reflected from
+ * a particular script.</p>
  *
- * <p>The primary source of elements are from scripts. A script that exports a
- * bind point for a data structure generates a Renderscript element to represent the
- * data exported by the script. The other common source of elements is from bitmap formats.</p>
+ * <p>Basic Elements are comprised of a {@link
+ * android.renderscript.Element.DataType} and a {@link
+ * android.renderscript.Element.DataKind}. The DataType encodes C type
+ * information of an Element, while the DataKind encodes how that Element should
+ * be interpreted by a {@link android.renderscript.Sampler}. Note that {@link
+ * android.renderscript.Allocation} objects with DataKind {@link
+ * android.renderscript.Element.DataKind#USER} cannot be used as input for a
+ * {@link android.renderscript.Sampler}. In general, {@link
+ * android.renderscript.Allocation} objects that are intended for use with a
+ * {@link android.renderscript.Sampler} should use bitmap-derived Elements such
+ * as {@link android.renderscript.Element#RGBA_8888} or {@link
+ * android.renderscript#Element.A_8}.</p>
  *
  * <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 Element extends BaseObj {
diff --git a/graphics/java/android/renderscript/FieldPacker.java b/graphics/java/android/renderscript/FieldPacker.java
index 730d973..fed97d6 100644
--- a/graphics/java/android/renderscript/FieldPacker.java
+++ b/graphics/java/android/renderscript/FieldPacker.java
@@ -21,7 +21,7 @@ import java.util.BitSet;
 
 /**
  * Utility class for packing arguments and structures from Android system objects to
- * Renderscript objects.
+ * RenderScript objects.
  *
  * This class is only intended to be used to support the
  * reflected code generated by the RS tool chain.  It should not
diff --git a/graphics/java/android/renderscript/FileA3D.java b/graphics/java/android/renderscript/FileA3D.java
index 8b0222a..e41f02d 100644
--- a/graphics/java/android/renderscript/FileA3D.java
+++ b/graphics/java/android/renderscript/FileA3D.java
@@ -30,9 +30,9 @@ import android.util.TypedValue;
 /**
  * @hide
  * @deprecated in API 16
- * FileA3D allows users to load Renderscript objects from files
+ * FileA3D allows users to load RenderScript objects from files
  * or resources stored on disk. It could be used to load items
- * such as 3D geometry data converted to a Renderscript format from
+ * such as 3D geometry data converted to a RenderScript format from
  * content creation tools. Currently only meshes are supported
  * in FileA3D.
  *
@@ -56,7 +56,7 @@ public class FileA3D extends BaseObj {
         UNKNOWN (0),
         /**
         * @deprecated in API 16
-        * Renderscript Mesh object
+        * RenderScript Mesh object
         **/
         MESH (1);
 
@@ -72,7 +72,7 @@ public class FileA3D extends BaseObj {
 
     /**
     * @deprecated in API 16
-    * IndexEntry contains information about one of the Renderscript
+    * IndexEntry contains information about one of the RenderScript
     * objects inside the file's index. It could be used to query the
     * object's type and also name and load the object itself if
     * necessary.
diff --git a/graphics/java/android/renderscript/Float2.java b/graphics/java/android/renderscript/Float2.java
index 1d4ce36..0f730fe 100644
--- a/graphics/java/android/renderscript/Float2.java
+++ b/graphics/java/android/renderscript/Float2.java
@@ -21,7 +21,7 @@ import android.util.Log;
 
 
 /**
- * Class for exposing the native Renderscript float2 type back to the Android system.
+ * Class for exposing the native RenderScript float2 type back to the Android system.
  *
  **/
 public class Float2 {
diff --git a/graphics/java/android/renderscript/Float3.java b/graphics/java/android/renderscript/Float3.java
index ffd1135..749865f 100644
--- a/graphics/java/android/renderscript/Float3.java
+++ b/graphics/java/android/renderscript/Float3.java
@@ -21,7 +21,7 @@ import android.util.Log;
 
 
 /**
- * Class for exposing the native Renderscript float2 type back to the Android system.
+ * Class for exposing the native RenderScript float2 type back to the Android system.
  *
  **/
 public class Float3 {
diff --git a/graphics/java/android/renderscript/Float4.java b/graphics/java/android/renderscript/Float4.java
index c7cc3ae..7ddf6aa 100644
--- a/graphics/java/android/renderscript/Float4.java
+++ b/graphics/java/android/renderscript/Float4.java
@@ -21,7 +21,7 @@ import android.util.Log;
 
 
 /**
- * Class for exposing the native Renderscript float2 type back to the Android system.
+ * Class for exposing the native RenderScript float2 type back to the Android system.
  *
  **/
 public class Float4 {
diff --git a/graphics/java/android/renderscript/Font.java b/graphics/java/android/renderscript/Font.java
index 1a8d5bf..0375d2b 100644
--- a/graphics/java/android/renderscript/Font.java
+++ b/graphics/java/android/renderscript/Font.java
@@ -39,7 +39,7 @@ import android.util.TypedValue;
  * faces, and different font sizes. During creation, the Android system quieries device's screen DPI to
  * ensure proper sizing across multiple device configurations.</p>
  * <p>Fonts are rendered using screen-space positions and no state setup beyond binding a
- * font to the Renderscript is required. A note of caution on performance, though the state changes
+ * font to the RenderScript is required. A note of caution on performance, though the state changes
  * are transparent to the user, they do happen internally, and it is more efficient to
  * render large batches of text in sequence. It is also more efficient to render multiple
  * characters at once instead of one by one to improve draw call batching.</p>
diff --git a/graphics/java/android/renderscript/Int2.java b/graphics/java/android/renderscript/Int2.java
index 434af21..71b5dd5 100644
--- a/graphics/java/android/renderscript/Int2.java
+++ b/graphics/java/android/renderscript/Int2.java
@@ -21,7 +21,7 @@ import android.util.Log;
 
 
 /**
- * Class for exposing the native Renderscript int2 type back to the Android system.
+ * Class for exposing the native RenderScript int2 type back to the Android system.
  *
  **/
 public class Int2 {
diff --git a/graphics/java/android/renderscript/Int3.java b/graphics/java/android/renderscript/Int3.java
index 333ccf8..719c908 100644
--- a/graphics/java/android/renderscript/Int3.java
+++ b/graphics/java/android/renderscript/Int3.java
@@ -21,7 +21,7 @@ import android.util.Log;
 
 
 /**
- * Class for exposing the native Renderscript int3 type back to the Android system.
+ * Class for exposing the native RenderScript int3 type back to the Android system.
  *
  **/
 public class Int3 {
diff --git a/graphics/java/android/renderscript/Int4.java b/graphics/java/android/renderscript/Int4.java
index 8734c95..eefb349 100644
--- a/graphics/java/android/renderscript/Int4.java
+++ b/graphics/java/android/renderscript/Int4.java
@@ -21,7 +21,7 @@ import android.util.Log;
 
 
 /**
- * Class for exposing the native Renderscript int4 type back to the Android system.
+ * Class for exposing the native RenderScript int4 type back to the Android system.
  *
  **/
 public class Int4 {
diff --git a/graphics/java/android/renderscript/Long2.java b/graphics/java/android/renderscript/Long2.java
index 95ea18c..bd8382d 100644
--- a/graphics/java/android/renderscript/Long2.java
+++ b/graphics/java/android/renderscript/Long2.java
@@ -21,7 +21,7 @@ import android.util.Log;
 
 
 /**
- * Class for exposing the native Renderscript long2 type back to the Android system.
+ * Class for exposing the native RenderScript long2 type back to the Android system.
  **/
 public class Long2 {
     public Long2() {
diff --git a/graphics/java/android/renderscript/Long3.java b/graphics/java/android/renderscript/Long3.java
index 96ee885..3e94942 100644
--- a/graphics/java/android/renderscript/Long3.java
+++ b/graphics/java/android/renderscript/Long3.java
@@ -21,7 +21,7 @@ import android.util.Log;
 
 
 /**
- * Class for exposing the native Renderscript long3 type back to the Android system.
+ * Class for exposing the native RenderScript long3 type back to the Android system.
  **/
 public class Long3 {
     public Long3() {
diff --git a/graphics/java/android/renderscript/Long4.java b/graphics/java/android/renderscript/Long4.java
index 50e664c..00fb7e6 100644
--- a/graphics/java/android/renderscript/Long4.java
+++ b/graphics/java/android/renderscript/Long4.java
@@ -21,7 +21,7 @@ import android.util.Log;
 
 
 /**
- * Class for exposing the native Renderscript long4 type back to the Android system.
+ * Class for exposing the native RenderScript long4 type back to the Android system.
  **/
 public class Long4 {
     public Long4() {
diff --git a/graphics/java/android/renderscript/Matrix2f.java b/graphics/java/android/renderscript/Matrix2f.java
index 39abd4f..d3621fa 100644
--- a/graphics/java/android/renderscript/Matrix2f.java
+++ b/graphics/java/android/renderscript/Matrix2f.java
@@ -21,7 +21,7 @@ import android.util.Log;
 
 
 /**
- * Class for exposing the native Renderscript rs_matrix2x2 type back to the Android system.
+ * Class for exposing the native RenderScript rs_matrix2x2 type back to the Android system.
  *
  **/
 public class Matrix2f {
diff --git a/graphics/java/android/renderscript/Matrix3f.java b/graphics/java/android/renderscript/Matrix3f.java
index 5e9a7ca..8c3c330 100644
--- a/graphics/java/android/renderscript/Matrix3f.java
+++ b/graphics/java/android/renderscript/Matrix3f.java
@@ -21,7 +21,7 @@ import android.util.Log;
 
 
 /**
- * Class for exposing the native Renderscript rs_matrix3x3 type back to the Android system.
+ * Class for exposing the native RenderScript rs_matrix3x3 type back to the Android system.
  *
  **/
 public class Matrix3f {
diff --git a/graphics/java/android/renderscript/Matrix4f.java b/graphics/java/android/renderscript/Matrix4f.java
index 4600424..cd18e30 100644
--- a/graphics/java/android/renderscript/Matrix4f.java
+++ b/graphics/java/android/renderscript/Matrix4f.java
@@ -21,7 +21,7 @@ import android.util.Log;
 
 
 /**
- * Class for exposing the native Renderscript rs_matrix4x4 type back to the Android system.
+ * Class for exposing the native RenderScript rs_matrix4x4 type back to the Android system.
  *
  **/
 public class Matrix4f {
diff --git a/graphics/java/android/renderscript/Mesh.java b/graphics/java/android/renderscript/Mesh.java
index d0d383d..bca4aa3 100644
--- a/graphics/java/android/renderscript/Mesh.java
+++ b/graphics/java/android/renderscript/Mesh.java
@@ -24,7 +24,7 @@ import android.util.Log;
  * @hide
  * @deprecated in API 16
  * <p>This class is a container for geometric data displayed with
- * Renderscript. Internally, a mesh is a collection of allocations that
+ * RenderScript. Internally, a mesh is a collection of allocations that
  * represent vertex data (positions, normals, texture
  * coordinates) and index data such as triangles and lines. </p>
  * <p>
@@ -32,7 +32,7 @@ import android.util.Log;
  * allocation that is provided separately, as multiple allocation
  * objects, or done as a combination of both. When a
  * vertex channel name matches an input in the vertex program,
- * Renderscript automatically connects the two together.
+ * RenderScript automatically connects the two together.
  * </p>
  * <p>
  *  Parts of the mesh can be rendered with either explicit
diff --git a/graphics/java/android/renderscript/Program.java b/graphics/java/android/renderscript/Program.java
index 9bd103e..bc2ca35 100644
--- a/graphics/java/android/renderscript/Program.java
+++ b/graphics/java/android/renderscript/Program.java
@@ -276,7 +276,7 @@ public class Program extends BaseObj {
             try {
                 mShader = new String(str, 0, strLength, "UTF-8");
             } catch (UnsupportedEncodingException e) {
-                Log.e("Renderscript shader creation", "Could not decode shader string");
+                Log.e("RenderScript shader creation", "Could not decode shader string");
             }
 
             return this;
diff --git a/graphics/java/android/renderscript/ProgramFragment.java b/graphics/java/android/renderscript/ProgramFragment.java
index dd0f9f5..b9ba3fd 100644
--- a/graphics/java/android/renderscript/ProgramFragment.java
+++ b/graphics/java/android/renderscript/ProgramFragment.java
@@ -23,7 +23,7 @@ import android.util.Log;
 /**
  * @hide
  * @deprecated in API 16
- * <p>The Renderscript fragment program, also known as fragment shader is responsible
+ * <p>The RenderScript fragment program, also known as fragment shader is responsible
  * for manipulating pixel data in a user defined way. It's constructed from a GLSL
  * shader string containing the program body, textures inputs, and a Type object
  * that describes the constants used by the program. Similar to the vertex programs,
diff --git a/graphics/java/android/renderscript/ProgramVertex.java b/graphics/java/android/renderscript/ProgramVertex.java
index 50e32f6..1c5a191 100644
--- a/graphics/java/android/renderscript/ProgramVertex.java
+++ b/graphics/java/android/renderscript/ProgramVertex.java
@@ -16,9 +16,9 @@
 
 /**
  * @hide
- * <p>The Renderscript vertex program, also known as a vertex shader, describes a stage in
+ * <p>The RenderScript vertex program, also known as a vertex shader, describes a stage in
  * the graphics pipeline responsible for manipulating geometric data in a user-defined way.
- * The object is constructed by providing the Renderscript system with the following data:</p>
+ * The object is constructed by providing the RenderScript system with the following data:</p>
  * <ul>
  *   <li>Element describing its varying inputs or attributes</li>
  *   <li>GLSL shader string that defines the body of the program</li>
@@ -28,7 +28,7 @@
  * <p>Once the program is created, you bind it to the graphics context, RenderScriptGL, and it will be used for
  * all subsequent draw calls until you bind a new program. If the program has constant inputs,
  * the user needs to bind an allocation containing those inputs. The allocation's type must match
- * the one provided during creation. The Renderscript library then does all the necessary plumbing
+ * the one provided during creation. The RenderScript library then does all the necessary plumbing
  * to send those constants to the graphics hardware. Varying inputs to the shader, such as position, normal,
  * and texture coordinates are matched by name between the input Element and the Mesh object being drawn.
  * The signatures don't have to be exact or in any strict order. As long as the input name in the shader
diff --git a/graphics/java/android/renderscript/RSDriverException.java b/graphics/java/android/renderscript/RSDriverException.java
index ce85b53..9e6507f 100644
--- a/graphics/java/android/renderscript/RSDriverException.java
+++ b/graphics/java/android/renderscript/RSDriverException.java
@@ -19,7 +19,7 @@ package android.renderscript;
 
 /**
  * Base class for all exceptions thrown by the Android
- * Renderscript
+ * RenderScript
  */
 public class RSDriverException extends RSRuntimeException {
     public RSDriverException(String string) {
diff --git a/graphics/java/android/renderscript/RSIllegalArgumentException.java b/graphics/java/android/renderscript/RSIllegalArgumentException.java
index 954c0e8..5c68594 100644
--- a/graphics/java/android/renderscript/RSIllegalArgumentException.java
+++ b/graphics/java/android/renderscript/RSIllegalArgumentException.java
@@ -19,7 +19,7 @@ package android.renderscript;
 
 /**
  * Base class for all exceptions thrown by the Android
- * Renderscript
+ * RenderScript
  */
 public class RSIllegalArgumentException extends RSRuntimeException {
     public RSIllegalArgumentException(String string) {
diff --git a/graphics/java/android/renderscript/RSInvalidStateException.java b/graphics/java/android/renderscript/RSInvalidStateException.java
index 691aeba..c881898 100644
--- a/graphics/java/android/renderscript/RSInvalidStateException.java
+++ b/graphics/java/android/renderscript/RSInvalidStateException.java
@@ -19,7 +19,7 @@ package android.renderscript;
 
 /**
  * Base class for all exceptions thrown by the Android
- * Renderscript
+ * RenderScript
  */
 public class RSInvalidStateException extends RSRuntimeException {
     public RSInvalidStateException(String string) {
diff --git a/graphics/java/android/renderscript/RSRuntimeException.java b/graphics/java/android/renderscript/RSRuntimeException.java
index 5a16478..b4b629e 100644
--- a/graphics/java/android/renderscript/RSRuntimeException.java
+++ b/graphics/java/android/renderscript/RSRuntimeException.java
@@ -19,7 +19,7 @@ package android.renderscript;
 
 /**
  * Base class for all exceptions thrown by the Android
- * Renderscript
+ * RenderScript
  */
 public class RSRuntimeException
   extends java.lang.RuntimeException {
diff --git a/graphics/java/android/renderscript/RSSurfaceView.java b/graphics/java/android/renderscript/RSSurfaceView.java
index 3c6c720..308d97a 100644
--- a/graphics/java/android/renderscript/RSSurfaceView.java
+++ b/graphics/java/android/renderscript/RSSurfaceView.java
@@ -36,8 +36,8 @@ import android.view.SurfaceView;
  *
  * <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 RSSurfaceView extends SurfaceView implements SurfaceHolder.Callback {
diff --git a/graphics/java/android/renderscript/RenderScript.java b/graphics/java/android/renderscript/RenderScript.java
index 8071073..4de4766 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() {
diff --git a/graphics/java/android/renderscript/RenderScriptGL.java b/graphics/java/android/renderscript/RenderScriptGL.java
index 52034b1..bac9c68 100644
--- a/graphics/java/android/renderscript/RenderScriptGL.java
+++ b/graphics/java/android/renderscript/RenderScriptGL.java
@@ -31,7 +31,7 @@ import android.view.SurfaceView;
 /**
  * @hide
  * @deprecated in API 16
- * The Graphics derivitive of Renderscript.  Extends the basic context to add a
+ * The Graphics derivitive of RenderScript.  Extends the basic context to add a
  * root script which is the display window for graphical output.  When the
  * system needs to update the display the currently bound root script will be
  * called.  This script is expected to issue the rendering commands to repaint
@@ -39,8 +39,8 @@ import android.view.SurfaceView;
  *
  * <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 RenderScriptGL extends RenderScript {
diff --git a/graphics/java/android/renderscript/Sampler.java b/graphics/java/android/renderscript/Sampler.java
index 057e9b5..623055f 100644
--- a/graphics/java/android/renderscript/Sampler.java
+++ b/graphics/java/android/renderscript/Sampler.java
@@ -28,9 +28,14 @@ import android.graphics.Bitmap;
 import android.graphics.BitmapFactory;
 
 /**
- * Sampler object which defines how data is extracted from textures. Samplers
- * are attached to Program objects (currently only ProgramFragment) when those objects
- * need to access texture data.
+ * Sampler object that defines how Allocations can be read as textures within a
+ * kernel. Samplers are used in conjunction with the {@code rsSample} runtime
+ * function to return values from normalized coordinates.
+ *
+ * Any Allocation used with a Sampler must have been created with {@link
+ * android.renderscript.Allocation#USAGE_GRAPHICS_TEXTURE}; using a Sampler on
+ * an {@link android.renderscript.Allocation} that was not created with {@link
+ * android.renderscript.Allocation#USAGE_GRAPHICS_TEXTURE} is undefined.
  **/
 public class Sampler extends BaseObj {
     public enum Value {
@@ -275,9 +280,8 @@ public class Sampler extends BaseObj {
     }
 
     /**
-     * Builder for creating non-standard samplers.  Usefull if mix and match of
-     * wrap modes is necesary or if anisotropic filtering is desired.
-     *
+     * Builder for creating non-standard samplers.  This is only necessary if
+     * a Sampler with different min and mag modes is desired.
      */
     public static class Builder {
         RenderScript mRS;
diff --git a/graphics/java/android/renderscript/Script.java b/graphics/java/android/renderscript/Script.java
index f0579ca..0026e0e 100644
--- a/graphics/java/android/renderscript/Script.java
+++ b/graphics/java/android/renderscript/Script.java
@@ -19,7 +19,8 @@ package android.renderscript;
 import android.util.SparseArray;
 
 /**
- *
+ * The parent class for all executable scripts. This should not be used by
+ * applications.
  **/
 public class Script extends BaseObj {
 
@@ -46,14 +47,6 @@ public class Script extends BaseObj {
     private final SparseArray<KernelID> mKIDs = new SparseArray<KernelID>();
     /**
      * Only to be used by generated reflected classes.
-     *
-     *
-     * @param slot
-     * @param sig
-     * @param ein
-     * @param eout
-     *
-     * @return KernelID
      */
     protected KernelID createKernelID(int slot, int sig, Element ein, Element eout) {
         KernelID k = mKIDs.get(slot);
@@ -92,11 +85,6 @@ public class Script extends BaseObj {
     private final SparseArray<FieldID> mFIDs = new SparseArray();
     /**
      * Only to be used by generated reflected classes.
-     *
-     * @param slot
-     * @param e
-     *
-     * @return FieldID
      */
     protected FieldID createFieldID(int slot, Element e) {
         FieldID f = mFIDs.get(slot);
@@ -118,7 +106,6 @@ public class Script extends BaseObj {
     /**
      * Only intended for use by generated reflected code.
      *
-     * @param slot
      */
     protected void invoke(int slot) {
         mRS.nScriptInvoke(getID(mRS), slot);
@@ -127,8 +114,6 @@ public class Script extends BaseObj {
     /**
      * Only intended for use by generated reflected code.
      *
-     * @param slot
-     * @param v
      */
     protected void invoke(int slot, FieldPacker v) {
         if (v != null) {
@@ -141,10 +126,6 @@ public class Script extends BaseObj {
     /**
      * Only intended for use by generated reflected code.
      *
-     * @param slot
-     * @param ain
-     * @param aout
-     * @param v
      */
     protected void forEach(int slot, Allocation ain, Allocation aout, FieldPacker v) {
         if (ain == null && aout == null) {
@@ -169,11 +150,6 @@ public class Script extends BaseObj {
     /**
      * Only intended for use by generated reflected code.
      *
-     * @param slot
-     * @param ain
-     * @param aout
-     * @param v
-     * @param sc
      */
     protected void forEach(int slot, Allocation ain, Allocation aout, FieldPacker v, LaunchOptions sc) {
         if (ain == null && aout == null) {
@@ -208,8 +184,6 @@ public class Script extends BaseObj {
     /**
      * Only intended for use by generated reflected code.
      *
-     * @param va
-     * @param slot
      */
     public void bindAllocation(Allocation va, int slot) {
         mRS.validate();
@@ -223,8 +197,6 @@ public class Script extends BaseObj {
     /**
      * Only intended for use by generated reflected code.
      *
-     * @param index
-     * @param v
      */
     public void setVar(int index, float v) {
         mRS.nScriptSetVarF(getID(mRS), index, v);
@@ -236,8 +208,6 @@ public class Script extends BaseObj {
     /**
      * Only intended for use by generated reflected code.
      *
-     * @param index
-     * @param v
      */
     public void setVar(int index, double v) {
         mRS.nScriptSetVarD(getID(mRS), index, v);
@@ -249,8 +219,6 @@ public class Script extends BaseObj {
     /**
      * Only intended for use by generated reflected code.
      *
-     * @param index
-     * @param v
      */
     public void setVar(int index, int v) {
         mRS.nScriptSetVarI(getID(mRS), index, v);
@@ -263,8 +231,6 @@ public class Script extends BaseObj {
     /**
      * Only intended for use by generated reflected code.
      *
-     * @param index
-     * @param v
      */
     public void setVar(int index, long v) {
         mRS.nScriptSetVarJ(getID(mRS), index, v);
@@ -277,8 +243,6 @@ public class Script extends BaseObj {
     /**
      * Only intended for use by generated reflected code.
      *
-     * @param index
-     * @param v
      */
     public void setVar(int index, boolean v) {
         mRS.nScriptSetVarI(getID(mRS), index, v ? 1 : 0);
@@ -290,8 +254,6 @@ public class Script extends BaseObj {
     /**
      * Only intended for use by generated reflected code.
      *
-     * @param index
-     * @param o
      */
     public void setVar(int index, BaseObj o) {
         mRS.nScriptSetVarObj(getID(mRS), index, (o == null) ? 0 : o.getID(mRS));
@@ -300,8 +262,6 @@ public class Script extends BaseObj {
     /**
      * Only intended for use by generated reflected code.
      *
-     * @param index
-     * @param v
      */
     public void setVar(int index, FieldPacker v) {
         mRS.nScriptSetVarV(getID(mRS), index, v.getData());
@@ -310,10 +270,6 @@ public class Script extends BaseObj {
     /**
      * Only intended for use by generated reflected code.
      *
-     * @param index
-     * @param v
-     * @param e
-     * @param dims
      */
     public void setVar(int index, FieldPacker v, Element e, int[] dims) {
         mRS.nScriptSetVarVE(getID(mRS), index, v.getData(), e.getID(mRS), dims);
@@ -322,8 +278,6 @@ public class Script extends BaseObj {
     /**
      * Only intended for use by generated reflected code.
      *
-     * @param index
-     * @param v
      */
     public void getVarV(int index, FieldPacker v) {
         mRS.nScriptGetVarV(getID(mRS), index, v.getData());
@@ -338,6 +292,10 @@ public class Script extends BaseObj {
         }
     }
 
+    /**
+     * Only intended for use by generated reflected code.
+     *
+     */
     public static class Builder {
         RenderScript mRS;
 
diff --git a/graphics/java/android/renderscript/ScriptC.java b/graphics/java/android/renderscript/ScriptC.java
index 6975534..b0a5759 100644
--- a/graphics/java/android/renderscript/ScriptC.java
+++ b/graphics/java/android/renderscript/ScriptC.java
@@ -30,7 +30,8 @@ import java.lang.reflect.Field;
 import java.lang.reflect.Modifier;
 
 /**
- *
+ * The superclass for all user-defined scripts. This is only
+ * intended to be used by the generated derived classes.
  **/
 public class ScriptC extends Script {
     private static final String TAG = "ScriptC";
diff --git a/graphics/java/android/renderscript/ScriptGroup.java b/graphics/java/android/renderscript/ScriptGroup.java
index 7afdb39..1416641 100644
--- a/graphics/java/android/renderscript/ScriptGroup.java
+++ b/graphics/java/android/renderscript/ScriptGroup.java
@@ -20,24 +20,26 @@ import java.lang.reflect.Method;
 import java.util.ArrayList;
 
 /**
- * ScriptGroup creates a groups of scripts which are executed
- * together based upon upon one execution call as if they were
- * all part of a single script.  The scripts may be connected
- * internally or to an external allocation. For the internal
- * connections the intermediate results are not observable after
- * the execution of the script.
+ * ScriptGroup creates a group of kernels that are executed
+ * together with one execution call as if they were a single kernel.
+ * The kernels may be connected internally or to an external allocation.
+ * The intermediate results for internal connections are not observable
+ * after the execution of the script.
  * <p>
- * The external connections are grouped into inputs and outputs.
+ * External connections are grouped into inputs and outputs.
  * All outputs are produced by a script kernel and placed into a
- * user supplied allocation. Inputs are similar but supply the
- * input of a kernal. Inputs bounds to a script are set directly
- * upon the script.
+ * user-supplied allocation. Inputs provide the input of a kernel.
+ * Inputs bound to script globals are set directly upon the script.
  * <p>
  * A ScriptGroup must contain at least one kernel. A ScriptGroup
  * must contain only a single directed acyclic graph (DAG) of
  * script kernels and connections. Attempting to create a
  * ScriptGroup with multiple DAGs or attempting to create
  * a cycle within a ScriptGroup will throw an exception.
+ * <p>
+ * Currently, all kernels in a ScriptGroup must be from separate
+ * Script objects. Attempting to use multiple kernels from the same
+ * Script object will result in an {@link android.renderscript.RSInvalidStateException}.
  *
  **/
 public final class ScriptGroup extends BaseObj {
@@ -93,8 +95,8 @@ public final class ScriptGroup extends BaseObj {
 
     /**
      * Sets an input of the ScriptGroup. This specifies an
-     * Allocation to be used for the kernels which require a kernel
-     * input and that input is provided external to the group.
+     * Allocation to be used for kernels that require an input
+     * Allocation provided from outside of the ScriptGroup.
      *
      * @param s The ID of the kernel where the allocation should be
      *          connected.
@@ -113,8 +115,8 @@ public final class ScriptGroup extends BaseObj {
 
     /**
      * Sets an output of the ScriptGroup. This specifies an
-     * Allocation to be used for the kernels which require a kernel
-     * output and that output is provided external to the group.
+     * Allocation to be used for the kernels that require an output
+     * Allocation visible after the ScriptGroup is executed.
      *
      * @param s The ID of the kernel where the allocation should be
      *          connected.
@@ -133,8 +135,8 @@ public final class ScriptGroup extends BaseObj {
 
     /**
      * Execute the ScriptGroup.  This will run all the kernels in
-     * the script.  The state of the connecting lines will not be
-     * observable after this operation.
+     * the ScriptGroup.  No internal connection results will be visible
+     * after execution of the ScriptGroup.
      */
     public void execute() {
         mRS.nScriptGroupExecute(getID(mRS));
@@ -142,20 +144,25 @@ public final class ScriptGroup extends BaseObj {
 
 
     /**
-     * Create a ScriptGroup. There are two steps to creating a
-     * ScriptGoup.
+     * Helper class to build a ScriptGroup. A ScriptGroup is
+     * created in two steps.
+     * <p>
+     * First, all kernels to be used by the ScriptGroup should be added.
      * <p>
-     * First all the Kernels to be used by the group should be
-     * added.  Once this is done the kernels should be connected.
-     * Kernels cannot be added once a connection has been made.
+     * Second, add connections between kernels. There are two types
+     * of connections: kernel to kernel and kernel to field.
+     * Kernel to kernel allows a kernel's output to be passed to
+     * another kernel as input. Kernel to field allows the output of
+     * one kernel to be bound as a script global. Kernel to kernel is
+     * higher performance and should be used where possible.
      * <p>
-     * Second, add connections. There are two forms of connections.
-     * Kernel to Kernel and Kernel to Field. Kernel to Kernel is
-     * higher performance and should be used where possible. The
-     * line of connections cannot form a loop. If a loop is detected
-     * an exception is thrown.
+     * A ScriptGroup must contain a single directed acyclic graph (DAG); it
+     * cannot contain cycles. Currently, all kernels used in a ScriptGroup
+     * must come from different Script objects. Additionally, all kernels
+     * in a ScriptGroup must have at least one input, output, or internal
+     * connection.
      * <p>
-     * Once all the connections are made a call to create will
+     * Once all connections are made, a call to {@link #create} will
      * return the ScriptGroup object.
      *
      */
@@ -166,10 +173,10 @@ public final class ScriptGroup extends BaseObj {
         private int mKernelCount;
 
         /**
-         * Create a builder for generating a ScriptGroup.
+         * Create a Builder for generating a ScriptGroup.
          *
          *
-         * @param rs The Renderscript context.
+         * @param rs The RenderScript context.
          */
         public Builder(RenderScript rs) {
             mRS = rs;
diff --git a/graphics/java/android/renderscript/ScriptIntrinsic3DLUT.java b/graphics/java/android/renderscript/ScriptIntrinsic3DLUT.java
index 86f37d8..34540a1 100644
--- a/graphics/java/android/renderscript/ScriptIntrinsic3DLUT.java
+++ b/graphics/java/android/renderscript/ScriptIntrinsic3DLUT.java
@@ -40,7 +40,7 @@ public final class ScriptIntrinsic3DLUT extends ScriptIntrinsic {
      *
      * The defaults tables are identity.
      *
-     * @param rs The Renderscript context
+     * @param rs The RenderScript context
      * @param e Element type for intputs and outputs
      *
      * @return ScriptIntrinsic3DLUT
@@ -55,6 +55,13 @@ public final class ScriptIntrinsic3DLUT extends ScriptIntrinsic {
         return new ScriptIntrinsic3DLUT(id, rs, e);
     }
 
+    /**
+     * Sets the {@link android.renderscript.Allocation} to be used as the lookup table.
+     *
+     * The lookup table must use the same {@link android.renderscript.Element} as the intrinsic.
+     *
+     */
+
     public void setLUT(Allocation lut) {
         final Type t = lut.getType();
 
diff --git a/graphics/java/android/renderscript/ScriptIntrinsicBlend.java b/graphics/java/android/renderscript/ScriptIntrinsicBlend.java
index 65c69c0..0e05bc8 100644
--- a/graphics/java/android/renderscript/ScriptIntrinsicBlend.java
+++ b/graphics/java/android/renderscript/ScriptIntrinsicBlend.java
@@ -18,8 +18,7 @@ package android.renderscript;
 
 
 /**
- * Intrinsic kernels for blending two buffers. Each blend function is a separate
- * kernel to make it easy to change between blend modes.
+ * Intrinsic kernels for blending two {@link android.renderscript.Allocation} objects.
  **/
 public class ScriptIntrinsicBlend extends ScriptIntrinsic {
     ScriptIntrinsicBlend(int id, RenderScript rs) {
@@ -27,11 +26,10 @@ public class ScriptIntrinsicBlend extends ScriptIntrinsic {
     }
 
     /**
-     * Supported elements types are uchar4
+     * Supported elements types are {@link Element#U8_4}
      *
-     *
-     * @param rs
-     * @param e
+     * @param rs The RenderScript context
+     * @param e Element type for inputs and outputs
      *
      * @return ScriptIntrinsicBlend
      */
@@ -53,7 +51,7 @@ public class ScriptIntrinsicBlend extends ScriptIntrinsic {
     }
 
     /**
-     * dst = {0, 0, 0, 0}
+     * Sets dst = {0, 0, 0, 0}
      *
      * @param ain The source buffer
      * @param aout The destination buffer
@@ -73,7 +71,7 @@ public class ScriptIntrinsicBlend extends ScriptIntrinsic {
 
 
     /**
-     * dst = src
+     * Sets dst = src
      *
      * @param ain The source buffer
      * @param aout The destination buffer
@@ -92,8 +90,9 @@ public class ScriptIntrinsicBlend extends ScriptIntrinsic {
     }
 
     /**
-     * dst = dst
-     * This is a NOP
+     * Sets dst = dst
+     *
+     * This is a NOP.
      *
      * @param ain The source buffer
      * @param aout The destination buffer
@@ -112,7 +111,7 @@ public class ScriptIntrinsicBlend extends ScriptIntrinsic {
     }
 
     /**
-     * dst = src + dst * (1.0 - src.a)
+     * Sets dst = src + dst * (1.0 - src.a)
      *
      * @param ain The source buffer
      * @param aout The destination buffer
@@ -131,7 +130,7 @@ public class ScriptIntrinsicBlend extends ScriptIntrinsic {
     }
 
     /**
-     * dst = dst + src * (1.0 - dst.a)
+     * Sets dst = dst + src * (1.0 - dst.a)
      *
      * @param ain The source buffer
      * @param aout The destination buffer
@@ -150,7 +149,7 @@ public class ScriptIntrinsicBlend extends ScriptIntrinsic {
     }
 
     /**
-     * dst = src * dst.a
+     * Sets dst = src * dst.a
      *
      * @param ain The source buffer
      * @param aout The destination buffer
@@ -169,7 +168,7 @@ public class ScriptIntrinsicBlend extends ScriptIntrinsic {
     }
 
     /**
-     * dst = dst * src.a
+     * Sets dst = dst * src.a
      *
      * @param ain The source buffer
      * @param aout The destination buffer
@@ -188,7 +187,7 @@ public class ScriptIntrinsicBlend extends ScriptIntrinsic {
     }
 
     /**
-     * dst = src * (1.0 - dst.a)
+     * Sets dst = src * (1.0 - dst.a)
      *
      * @param ain The source buffer
      * @param aout The destination buffer
@@ -207,7 +206,7 @@ public class ScriptIntrinsicBlend extends ScriptIntrinsic {
     }
 
     /**
-     * dst = dst * (1.0 - src.a)
+     * Sets dst = dst * (1.0 - src.a)
      *
      * @param ain The source buffer
      * @param aout The destination buffer
@@ -266,7 +265,7 @@ public class ScriptIntrinsicBlend extends ScriptIntrinsic {
     }
 
     /**
-     * dst = {src.r ^ dst.r, src.g ^ dst.g, src.b ^ dst.b, src.a ^ dst.a}
+     * Sets dst = {src.r ^ dst.r, src.g ^ dst.g, src.b ^ dst.b, src.a ^ dst.a}
      *
      * @param ain The source buffer
      * @param aout The destination buffer
@@ -295,7 +294,7 @@ public class ScriptIntrinsicBlend extends ScriptIntrinsic {
     }
 */
     /**
-     * dst = src * dst
+     * Sets dst = src * dst
      *
      * @param ain The source buffer
      * @param aout The destination buffer
@@ -391,7 +390,7 @@ public class ScriptIntrinsicBlend extends ScriptIntrinsic {
     }
 */
     /**
-     * dst = min(src + dst, 1.0)
+     * Sets dst = min(src + dst, 1.0)
      *
      * @param ain The source buffer
      * @param aout The destination buffer
@@ -410,7 +409,7 @@ public class ScriptIntrinsicBlend extends ScriptIntrinsic {
     }
 
     /**
-     * dst = max(dst - src, 0.0)
+     * Sets dst = max(dst - src, 0.0)
      *
      * @param ain The source buffer
      * @param aout The destination buffer
diff --git a/graphics/java/android/renderscript/ScriptIntrinsicBlur.java b/graphics/java/android/renderscript/ScriptIntrinsicBlur.java
index 2848f64..aaf5ffc 100644
--- a/graphics/java/android/renderscript/ScriptIntrinsicBlur.java
+++ b/graphics/java/android/renderscript/ScriptIntrinsicBlur.java
@@ -40,7 +40,7 @@ public final class ScriptIntrinsicBlur extends ScriptIntrinsic {
      *
      * Supported elements types are {@link Element#U8_4}
      *
-     * @param rs The Renderscript context
+     * @param rs The RenderScript context
      * @param e Element type for inputs and outputs
      *
      * @return ScriptIntrinsicBlur
diff --git a/graphics/java/android/renderscript/ScriptIntrinsicColorMatrix.java b/graphics/java/android/renderscript/ScriptIntrinsicColorMatrix.java
index f7e844e..77b9385 100644
--- a/graphics/java/android/renderscript/ScriptIntrinsicColorMatrix.java
+++ b/graphics/java/android/renderscript/ScriptIntrinsicColorMatrix.java
@@ -41,7 +41,7 @@ public final class ScriptIntrinsicColorMatrix extends ScriptIntrinsic {
      *
      * Supported elements types are {@link Element#U8_4}
      *
-     * @param rs The Renderscript context
+     * @param rs The RenderScript context
      * @param e Element type for intputs and outputs
      *
      * @return ScriptIntrinsicColorMatrix
diff --git a/graphics/java/android/renderscript/ScriptIntrinsicConvolve3x3.java b/graphics/java/android/renderscript/ScriptIntrinsicConvolve3x3.java
index d54df96..c9c54b2 100644
--- a/graphics/java/android/renderscript/ScriptIntrinsicConvolve3x3.java
+++ b/graphics/java/android/renderscript/ScriptIntrinsicConvolve3x3.java
@@ -41,7 +41,7 @@ public final class ScriptIntrinsicConvolve3x3 extends ScriptIntrinsic {
      * <p> [ 0,  0,  0 ]
      * </code>
      *
-     * @param rs The Renderscript context
+     * @param rs The RenderScript context
      * @param e Element type for intputs and outputs
      *
      * @return ScriptIntrinsicConvolve3x3
diff --git a/graphics/java/android/renderscript/ScriptIntrinsicConvolve5x5.java b/graphics/java/android/renderscript/ScriptIntrinsicConvolve5x5.java
index 1f52e3f..c6e1e39 100644
--- a/graphics/java/android/renderscript/ScriptIntrinsicConvolve5x5.java
+++ b/graphics/java/android/renderscript/ScriptIntrinsicConvolve5x5.java
@@ -42,7 +42,7 @@ public final class ScriptIntrinsicConvolve5x5 extends ScriptIntrinsic {
      * <p> [ 0,  0,  0,  0,  0  ]
      * </code>
      *
-     * @param rs The Renderscript context
+     * @param rs The RenderScript context
      * @param e Element type for intputs and outputs
      *
      * @return ScriptIntrinsicConvolve5x5
diff --git a/graphics/java/android/renderscript/ScriptIntrinsicLUT.java b/graphics/java/android/renderscript/ScriptIntrinsicLUT.java
index f5ca261..0f7ab38 100644
--- a/graphics/java/android/renderscript/ScriptIntrinsicLUT.java
+++ b/graphics/java/android/renderscript/ScriptIntrinsicLUT.java
@@ -47,7 +47,7 @@ public final class ScriptIntrinsicLUT extends ScriptIntrinsic {
      *
      * The defaults tables are identity.
      *
-     * @param rs The Renderscript context
+     * @param rs The RenderScript context
      * @param e Element type for intputs and outputs
      *
      * @return ScriptIntrinsicLUT
diff --git a/graphics/java/android/renderscript/ScriptIntrinsicYuvToRGB.java b/graphics/java/android/renderscript/ScriptIntrinsicYuvToRGB.java
index dc8a5aa..9b5de9b 100644
--- a/graphics/java/android/renderscript/ScriptIntrinsicYuvToRGB.java
+++ b/graphics/java/android/renderscript/ScriptIntrinsicYuvToRGB.java
@@ -36,7 +36,7 @@ public final class ScriptIntrinsicYuvToRGB extends ScriptIntrinsic {
      *
      * Supported elements types are {@link Element#U8_4}
      *
-     * @param rs The Renderscript context
+     * @param rs The RenderScript context
      * @param e Element type for output
      *
      * @return ScriptIntrinsicYuvToRGB
diff --git a/graphics/java/android/renderscript/Short2.java b/graphics/java/android/renderscript/Short2.java
index 617f1f5..7c6027f 100644
--- a/graphics/java/android/renderscript/Short2.java
+++ b/graphics/java/android/renderscript/Short2.java
@@ -21,7 +21,7 @@ import android.util.Log;
 
 
 /**
- * Class for exposing the native Renderscript Short2 type back to the Android system.
+ * Class for exposing the native RenderScript Short2 type back to the Android system.
  *
  **/
 public class Short2 {
diff --git a/graphics/java/android/renderscript/Short3.java b/graphics/java/android/renderscript/Short3.java
index b9ca49b..49de05e 100644
--- a/graphics/java/android/renderscript/Short3.java
+++ b/graphics/java/android/renderscript/Short3.java
@@ -21,7 +21,7 @@ import android.util.Log;
 
 
 /**
- * Class for exposing the native Renderscript short3 type back to the Android system.
+ * Class for exposing the native RenderScript short3 type back to the Android system.
  *
  **/
 public class Short3 {
diff --git a/graphics/java/android/renderscript/Short4.java b/graphics/java/android/renderscript/Short4.java
index d5f2db5..a7807a4 100644
--- a/graphics/java/android/renderscript/Short4.java
+++ b/graphics/java/android/renderscript/Short4.java
@@ -21,7 +21,7 @@ import android.util.Log;
 
 
 /**
- * Class for exposing the native Renderscript short4 type back to the Android system.
+ * Class for exposing the native RenderScript short4 type back to the Android system.
  *
  **/
 public class Short4 {
diff --git a/graphics/java/android/renderscript/Type.java b/graphics/java/android/renderscript/Type.java
index a5e24ce..ef08c29 100644
--- a/graphics/java/android/renderscript/Type.java
+++ b/graphics/java/android/renderscript/Type.java
@@ -23,24 +23,29 @@ import android.graphics.ImageFormat;
 import android.util.Log;
 
 /**
- * <p>Type is an allocation template. It consists of an Element and one or more
- * dimensions. It describes only the layout of memory but does not allocate any
- * storage for the data that is described.</p>
+ * <p>A Type describes the {@link android.renderscript.Element} and dimensions used for an {@link
+ * android.renderscript.Allocation} or a parallel operation. Types are created through {@link
+ * android.renderscript.Type.Builder}.</p>
  *
- * <p>A Type consists of several dimensions. Those are X, Y, Z, LOD (level of
- * detail), Faces (faces of a cube map).  The X,Y,Z dimensions can be assigned
- * any positive integral value within the constraints of available memory.  A
- * single dimension allocation would have an X dimension of greater than zero
- * while the Y and Z dimensions would be zero to indicate not present.  In this
- * regard an allocation of x=10, y=1 would be considered 2 dimensionsal while
- * x=10, y=0 would be considered 1 dimensional.</p>
+ * <p>A Type always includes an {@link android.renderscript.Element} and an X
+ * dimension. A Type may be multidimensional, up to three dimensions. A nonzero
+ * value in the Y or Z dimensions indicates that the dimension is present. Note
+ * that a Type with only a given X dimension and a Type with the same X
+ * dimension but Y = 1 are not equivalent.</p>
  *
- * <p>The LOD and Faces dimensions are booleans to indicate present or not present.</p>
+ * <p>A Type also supports inclusion of level of detail (LOD) or cube map
+ * faces. LOD and cube map faces are booleans to indicate present or not
+ * present. </p>
+ *
+ * <p>A Type also supports YUV format information to support an {@link
+ * android.renderscript.Allocation} in a YUV format. The YUV formats supported
+ * are {@link android.graphics.ImageFormat#YV12} and {@link
+ * android.graphics.ImageFormat#NV21}.</p>
  *
  * <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 Type extends BaseObj {
@@ -277,11 +282,9 @@ public class Type extends BaseObj {
         }
 
         /**
-         * Set the YUV layout for a Type.  This controls how the memory is
-         * interpreted.  Generally and application should not need to call this
-         * function and it would be set by the Camera.
+         * Set the YUV layout for a Type.
          *
-         * only NV21, YV12.  Enums from ImageFormat
+         * @param yuvFormat {@link android.graphics.ImageFormat#YV12} or {@link android.graphics.ImageFormat#NV21}
          */
         public Builder setYuvFormat(int yuvFormat) {
             switch (yuvFormat) {
@@ -299,7 +302,7 @@ public class Type extends BaseObj {
 
 
         /**
-         * Validate structure and create a new type.
+         * Validate structure and create a new Type.
          *
          * @return Type
          */
diff --git a/graphics/java/android/renderscript/package.html b/graphics/java/android/renderscript/package.html
index eb178c1..a844956 100644
--- a/graphics/java/android/renderscript/package.html
+++ b/graphics/java/android/renderscript/package.html
@@ -2,6 +2,11 @@
 <BODY>
 <p>RenderScript provides support for high-performance computation across heterogeneous processors.</p>
 
+<p>This package is for the latest native version of RenderScript included on
+Android devices. Developers interested in running RenderScript on any Android
+device running {@link android.os.Build.VERSION_CODES#GINGERBREAD} or newer
+should see the {@link android.support.v8.renderscript} package.
+
 <p>For more information, see the
 <a href="{@docRoot}guide/topics/renderscript/index.html">RenderScript</a> developer guide.</p>
 {@more}