Docs plus removing some junk per API review.

Change-Id: I45f995b656754550be68c78e467071d6e59b348f

9 files changed, 102 insertions, 50 deletions

diff --git a/graphics/java/android/renderscript/Allocation.java b/graphics/java/android/renderscript/Allocation.java
index b15121a..579f314 100644
--- a/graphics/java/android/renderscript/Allocation.java
+++ b/graphics/java/android/renderscript/Allocation.java
@@ -503,7 +503,7 @@ public class Allocation extends BaseObj {
      * Creates a renderscript allocation with the size specified by
      * the type and no mipmaps generated by default
      *
-     * @param rs
+     * @param rs Context to which the allocation will belong.
      * @param type renderscript type describing data layout
      * @param usage bit field specifying how the allocation is
      *              utilized
@@ -519,7 +519,7 @@ public class Allocation extends BaseObj {
      * the size specified by the type and no mipmaps generated by
      * default
      *
-     * @param rs
+     * @param rs Context to which the allocation will belong.
      * @param type renderscript type describing data layout
      *
      * @return allocation
@@ -532,7 +532,7 @@ public class Allocation extends BaseObj {
      * Creates a renderscript allocation with a specified number of
      * given elements
      *
-     * @param rs
+     * @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
@@ -558,7 +558,7 @@ public class Allocation extends BaseObj {
      * Creates a renderscript allocation with a specified number of
      * given elements
      *
-     * @param rs
+     * @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
      *
@@ -598,7 +598,7 @@ public class Allocation extends BaseObj {
     /**
      * Creates a renderscript allocation from a bitmap
      *
-     * @param rs
+     * @param rs Context to which the allocation will belong.
      * @param b bitmap source for the allocation data
      * @param mips specifies desired mipmap behaviour for the
      *             allocation
@@ -625,7 +625,7 @@ public class Allocation extends BaseObj {
      * Creates a non-mipmapped renderscript allocation to use as a
      * graphics texture
      *
-     * @param rs
+     * @param rs Context to which the allocation will belong.
      * @param b bitmap source for the allocation data
      *
      * @return renderscript allocation containing bitmap data
@@ -641,7 +641,7 @@ public class Allocation extends BaseObj {
      * horizontal list of cube faces. Each individual face must be
      * the same size and power of 2
      *
-     * @param rs
+     * @param rs Context to which the allocation will belong.
      * @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
@@ -690,7 +690,7 @@ public class Allocation extends BaseObj {
      * of cube faces. Each individual face must be the same size and
      * power of 2
      *
-     * @param rs
+     * @param rs Context to which the allocation will belong.
      * @param b bitmap with cubemap faces layed out in the following
      *          format: right, left, top, bottom, front, back
      *
@@ -708,7 +708,7 @@ public class Allocation extends BaseObj {
      * the cube faces. All the faces must be the same size and
      * power of 2
      *
-     * @param rs
+     * @param rs Context to which the allocation will belong.
      * @param xpos cubemap face in the positive x direction
      * @param xneg cubemap face in the negative x direction
      * @param ypos cubemap face in the positive y direction
@@ -776,7 +776,7 @@ public class Allocation extends BaseObj {
      * the cube faces. All the faces must be the same size and
      * power of 2
      *
-     * @param rs
+     * @param rs Context to which the allocation will belong.
      * @param xpos cubemap face in the positive x direction
      * @param xneg cubemap face in the negative x direction
      * @param ypos cubemap face in the positive y direction
@@ -803,7 +803,7 @@ public class Allocation extends BaseObj {
      * Creates a renderscript allocation from the bitmap referenced
      * by resource id
      *
-     * @param rs
+     * @param rs Context to which the allocation will belong.
      * @param res application resources
      * @param id resource id to load the data from
      * @param mips specifies desired mipmap behaviour for the
@@ -831,7 +831,7 @@ public class Allocation extends BaseObj {
      * Creates a non-mipmapped renderscript allocation to use as a
      * graphics texture from the bitmap referenced by resource id
      *
-     * @param rs
+     * @param rs Context to which the allocation will belong.
      * @param res application resources
      * @param id resource id to load the data from
      *
@@ -850,7 +850,7 @@ public class Allocation extends BaseObj {
      * Creates a renderscript allocation containing string data
      * encoded in UTF-8 format
      *
-     * @param rs
+     * @param rs Context to which the allocation will belong.
      * @param str string to create the allocation from
      * @param usage bit field specifying how the allocaiton is
      *              utilized
diff --git a/graphics/java/android/renderscript/FileA3D.java b/graphics/java/android/renderscript/FileA3D.java
index 90d102c..fe3971a 100644
--- a/graphics/java/android/renderscript/FileA3D.java
+++ b/graphics/java/android/renderscript/FileA3D.java
@@ -28,22 +28,22 @@ import android.util.Log;
 import android.util.TypedValue;
 
 /**
+ * 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 a renderscript format from
+ * content creation tools. Currently only meshes are supported
+ * in FileA3D.
+ *
+ * When successfully loaded, FileA3D will contain a list of
+ * index entries for all the objects stored inside it.
  *
  **/
 public class FileA3D extends BaseObj {
 
-    // This will go away in the clean up pass,
-    // trying to avoid multiproject submits
-    public enum ClassID {
-
-        UNKNOWN,
-        MESH;
-
-        public static ClassID toClassID(int intID) {
-            return ClassID.values()[intID];
-        }
-    }
-
+    /**
+    * Specifies what renderscript object type is contained within
+    * the FileA3D IndexEntry
+    **/
     public enum EntryType {
 
         UNKNOWN (0),
@@ -59,34 +59,48 @@ public class FileA3D extends BaseObj {
         }
     }
 
-    // Read only class with index entries
+    /**
+    * 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 name and load the object itself if
+    * necessary.
+    */
     public static class IndexEntry {
         RenderScript mRS;
         int mIndex;
         int mID;
         String mName;
-        ClassID mClassID;
         EntryType mEntryType;
         BaseObj mLoadedObj;
 
+        /**
+        * @return name of a renderscript object the index entry
+        *         describes
+        */
         public String getName() {
             return mName;
         }
 
-        public ClassID getClassID() {
-            return mClassID;
-        }
-
+        /**
+        * @return type of a renderscript object the index entry
+        *         describes
+        */
         public EntryType getEntryType() {
             return mEntryType;
         }
 
+        /**
+        * @return renderscript object described by the entry
+        */
         public BaseObj getObject() {
             mRS.validate();
             BaseObj obj = internalCreate(mRS, this);
             return obj;
         }
 
+        /**
+        * @return renderscript mesh object described by the entry
+        */
         public Mesh getMesh() {
             return (Mesh)getObject();
         }
@@ -122,7 +136,6 @@ public class FileA3D extends BaseObj {
             mID = id;
             mName = name;
             mEntryType = type;
-            mClassID = mEntryType == EntryType.MESH ? ClassID.MESH : ClassID.UNKNOWN;
             mLoadedObj = null;
         }
     }
@@ -152,6 +165,9 @@ public class FileA3D extends BaseObj {
         }
     }
 
+    /**
+    * @return the numberof objects stored inside a FileA3D
+    */
     public int getIndexEntryCount() {
         if(mFileEntries == null) {
             return 0;
@@ -159,6 +175,12 @@ public class FileA3D extends BaseObj {
         return mFileEntries.length;
     }
 
+    /**
+    * Returns an index entry from the list of all objects inside
+    * FileA3D
+    *
+    * @param index number of the entry from the list to return
+    */
     public IndexEntry getIndexEntry(int index) {
         if(getIndexEntryCount() == 0 || index < 0 || index >= mFileEntries.length) {
             return null;
@@ -166,6 +188,14 @@ public class FileA3D extends BaseObj {
         return mFileEntries[index];
     }
 
+    /**
+    * Creates a FileA3D object from an asset stored on disk
+    *
+    * @param rs Context to which the object will belong.
+    * @param mgr asset manager used to load asset
+    * @param path location of the file to load
+    *
+    */
     static public FileA3D createFromAsset(RenderScript rs, AssetManager mgr, String path) {
         rs.validate();
         int fileId = rs.nFileA3DCreateFromAsset(mgr, path);
@@ -178,6 +208,13 @@ public class FileA3D extends BaseObj {
         return fa3d;
     }
 
+    /**
+    * Creates a FileA3D object from a file stored on disk
+    *
+    * @param rs Context to which the object will belong.
+    * @param path location of the file to load
+    *
+    */
     static public FileA3D createFromFile(RenderScript rs, String path) {
         int fileId = rs.nFileA3DCreateFromFile(path);
 
@@ -189,10 +226,25 @@ public class FileA3D extends BaseObj {
         return fa3d;
     }
 
+    /**
+    * Creates a FileA3D object from a file stored on disk
+    *
+    * @param rs Context to which the object will belong.
+    * @param path location of the file to load
+    *
+    */
     static public FileA3D createFromFile(RenderScript rs, File path) {
         return createFromFile(rs, path.getAbsolutePath());
     }
 
+    /**
+    * Creates a FileA3D object from an application resource
+    *
+    * @param rs Context to which the object will belong.
+    * @param res resource manager used for loading
+    * @param id resource to create FileA3D from
+    *
+    */
     static public FileA3D createFromResource(RenderScript rs, Resources res, int id) {
 
         rs.validate();
diff --git a/graphics/java/android/renderscript/Mesh.java b/graphics/java/android/renderscript/Mesh.java
index f1f1237..fcf8178 100644
--- a/graphics/java/android/renderscript/Mesh.java
+++ b/graphics/java/android/renderscript/Mesh.java
@@ -172,7 +172,7 @@ public class Mesh extends BaseObj {
 
         /**
         * Creates builder object
-        * @param rs
+        * @param rs Context to which the mesh will belong.
         * @param usage specifies how the mesh allocations are to be
         *              handled, whether they need to be uploaded to a
         *              buffer on the gpu, maintain a cpu copy, etc
@@ -512,7 +512,7 @@ public class Mesh extends BaseObj {
         public static final int TEXTURE_0 = 0x0100;
 
         /**
-        * @param rs
+        * @param rs Context to which the mesh will belong.
         * @param vtxSize specifies whether the vertex is a float2 or
         *                float3
         * @param flags bitfield that is a combination of COLOR, NORMAL,
diff --git a/graphics/java/android/renderscript/ProgramFragment.java b/graphics/java/android/renderscript/ProgramFragment.java
index 14c0c01..333880d 100644
--- a/graphics/java/android/renderscript/ProgramFragment.java
+++ b/graphics/java/android/renderscript/ProgramFragment.java
@@ -36,7 +36,7 @@ public class ProgramFragment extends Program {
         /**
          * Create a builder object.
          *
-         * @param rs
+         * @param rs Context to which the program will belong.
          */
         public Builder(RenderScript rs) {
             super(rs);
diff --git a/graphics/java/android/renderscript/ProgramFragmentFixedFunction.java b/graphics/java/android/renderscript/ProgramFragmentFixedFunction.java
index 663bc9f..1af31f8 100644
--- a/graphics/java/android/renderscript/ProgramFragmentFixedFunction.java
+++ b/graphics/java/android/renderscript/ProgramFragmentFixedFunction.java
@@ -194,7 +194,7 @@ public class ProgramFragmentFixedFunction extends ProgramFragment {
         /**
          * Creates a builder for fixed function fragment program
          *
-         * @param rs
+         * @param rs Context to which the program will belong.
          */
         public Builder(RenderScript rs) {
             mRS = rs;
diff --git a/graphics/java/android/renderscript/ProgramStore.java b/graphics/java/android/renderscript/ProgramStore.java
index d79900e..9128f9b 100644
--- a/graphics/java/android/renderscript/ProgramStore.java
+++ b/graphics/java/android/renderscript/ProgramStore.java
@@ -149,7 +149,7 @@ public class ProgramStore extends BaseObj {
     *  - incoming pixels override the value stored in the color
     *    buffer if it passes the depth test
     *
-    *  @param rs
+    *  @param rs Context to which the program will belong.
     **/
     public static ProgramStore BLEND_NONE_DEPTH_TEST(RenderScript rs) {
         if(rs.mProgramStore_BLEND_NONE_DEPTH_TEST == null) {
@@ -170,7 +170,7 @@ public class ProgramStore extends BaseObj {
     *  - incoming pixels override the value stored in the color
     *    buffer
     *
-    *  @param rs
+    *  @param rs Context to which the program will belong.
     **/
     public static ProgramStore BLEND_NONE_DEPTH_NONE(RenderScript rs) {
         if(rs.mProgramStore_BLEND_NONE_DEPTH_NO_DEPTH == null) {
@@ -194,7 +194,7 @@ public class ProgramStore extends BaseObj {
     *    following formula
     *  Final.RGB = Source.RGB * Source.A + Dest.RGB * (1 - Source.A)
     *
-    *  @param rs
+    *  @param rs Context to which the program will belong.
     **/
     public static ProgramStore BLEND_ALPHA_DEPTH_TEST(RenderScript rs) {
         if(rs.mProgramStore_BLEND_ALPHA_DEPTH_TEST == null) {
@@ -216,7 +216,7 @@ public class ProgramStore extends BaseObj {
     *    (Dest) using the following formula
     *  Final.RGB = Source.RGB * Source.A + Dest.RGB * (1 - Source.A)
     *
-    *  @param rs
+    *  @param rs Context to which the program will belong.
     **/
     public static ProgramStore BLEND_ALPHA_DEPTH_NONE(RenderScript rs) {
         if(rs.mProgramStore_BLEND_ALPHA_DEPTH_NO_DEPTH == null) {
diff --git a/graphics/java/android/renderscript/ProgramVertex.java b/graphics/java/android/renderscript/ProgramVertex.java
index 7ba8b82..a965b81 100644
--- a/graphics/java/android/renderscript/ProgramVertex.java
+++ b/graphics/java/android/renderscript/ProgramVertex.java
@@ -46,7 +46,7 @@ public class ProgramVertex extends Program {
         /**
          * Create a builder object.
          *
-         * @param rs
+         * @param rs Context to which the program will belong.
          */
         public Builder(RenderScript rs) {
             super(rs);
diff --git a/graphics/java/android/renderscript/ProgramVertexFixedFunction.java b/graphics/java/android/renderscript/ProgramVertexFixedFunction.java
index b9537c7..666c7ec 100644
--- a/graphics/java/android/renderscript/ProgramVertexFixedFunction.java
+++ b/graphics/java/android/renderscript/ProgramVertexFixedFunction.java
@@ -105,7 +105,7 @@ public class ProgramVertexFixedFunction extends ProgramVertex {
         /**
          * Creates a builder for fixed function vertex program
          *
-         * @param rs
+         * @param rs Context to which the program will belong.
          */
         public Builder(RenderScript rs) {
             mRS = rs;
@@ -196,9 +196,9 @@ public class ProgramVertexFixedFunction extends ProgramVertex {
         private FieldPacker mIOBuffer;
 
         /**
-        * Creates buffer to store fixed function emulation matrices
+        * Creates a buffer to store fixed function emulation matrices
         *
-        * @param rs
+        * @param rs Context to which the allocation will belong.
         **/
         public Constants(RenderScript rs) {
             Type constInputType = ProgramVertexFixedFunction.Builder.getConstantInputType(rs);
diff --git a/graphics/java/android/renderscript/Sampler.java b/graphics/java/android/renderscript/Sampler.java
index 57a9889..c656d75 100644
--- a/graphics/java/android/renderscript/Sampler.java
+++ b/graphics/java/android/renderscript/Sampler.java
@@ -56,7 +56,7 @@ public class Sampler extends BaseObj {
      * Retrieve a sampler with min and mag set to nearest and wrap modes set to
      * clamp.
      *
-     * @param rs
+     * @param rs Context to which the sampler will belong.
      *
      * @return Sampler
      */
@@ -76,7 +76,7 @@ public class Sampler extends BaseObj {
      * Retrieve a sampler with min and mag set to linear and wrap modes set to
      * clamp.
      *
-     * @param rs
+     * @param rs Context to which the sampler will belong.
      *
      * @return Sampler
      */
@@ -96,7 +96,7 @@ public class Sampler extends BaseObj {
      * Retrieve a sampler with ag set to linear, min linear mipmap linear, and
      * to and wrap modes set to clamp.
      *
-     * @param rs
+     * @param rs Context to which the sampler will belong.
      *
      * @return Sampler
      */
@@ -116,7 +116,7 @@ public class Sampler extends BaseObj {
      * Retrieve a sampler with min and mag set to nearest and wrap modes set to
      * wrap.
      *
-     * @param rs
+     * @param rs Context to which the sampler will belong.
      *
      * @return Sampler
      */
@@ -136,7 +136,7 @@ public class Sampler extends BaseObj {
      * Retrieve a sampler with min and mag set to nearest and wrap modes set to
      * wrap.
      *
-     * @param rs
+     * @param rs Context to which the sampler will belong.
      *
      * @return Sampler
      */
@@ -156,7 +156,7 @@ public class Sampler extends BaseObj {
      * Retrieve a sampler with ag set to linear, min linear mipmap linear, and
      * to and wrap modes set to wrap.
      *
-     * @param rs
+     * @param rs Context to which the sampler will belong.
      *
      * @return Sampler
      */