* Javadocs for com.jme3.scene

git-svn-id: https://jmonkeyengine.googlecode.com/svn/trunk@7663 75d07b2b-3a1a-0410-a2c5-0572b91ccdca

engine/src/core/com/jme3/renderer/queue/RenderQueue.java

@@ -31,6 +31,7 @@
  */
 package com.jme3.renderer.queue;
 
+import com.jme3.post.SceneProcessor;
 import com.jme3.renderer.Camera;
 import com.jme3.renderer.RenderManager;
 import com.jme3.scene.Geometry;
@@ -56,22 +57,97 @@ public class RenderQueue {
         this.shadowCast = new GeometryList(new OpaqueComparator());
     }
 
+    /**
+     * The render queue <code>Bucket</code> specifies the bucket
+     * to which the spatial will be placed when rendered. 
+     * <p>
+     * The behavior of the rendering will differ depending on which 
+     * bucket the spatial is placed. A spatial's queue bucket can be set
+     * via {@link Spatial#setQueueBucket(com.jme3.renderer.queue.RenderQueue.Bucket) }.
+     */
     public enum Bucket {
-
+        /**
-        Gui,
+         * The renderer will try to find the optimal order for rendering all 
+         * objects using this mode.
+         * You should use this mode for most normal objects, except transparent
+         * ones, as it could give a nice performance boost to your application.
+         */
         Opaque,
-        Sky,
+        
+        /**
+         * This is the mode you should use for object with
+         * transparency in them. It will ensure the objects furthest away are
+         * rendered first. That ensures when another transparent object is drawn on
+         * top of previously drawn objects, you can see those (and the object drawn
+         * using Opaque) through the transparent parts of the newly drawn
+         * object. 
+         */
         Transparent,
+        
+        /**
+         * A special mode used for rendering really far away, flat objects - 
+         * e.g. skies. In this mode, the depth is set to infinity so 
+         * spatials in this bucket will appear behind everything, the downside
+         * to this bucket is that 3D objects will not be rendered correctly
+         * due to lack of depth testing.
+         */
+        Sky,
+        
+        /**
+         * A special mode used for rendering transparent objects that
+         * should not be effected by {@link SceneProcessor}. 
+         * Generally this would contain translucent objects, and
+         * also objects that do not write to the depth buffer such as
+         * particle emitters.
+         */
         Translucent,
+        
+        /**
+         * This is a special mode, for drawing 2D object
+         * without perspective (such as GUI or HUD parts).
+         * The spatial's world coordinate system has the range
+         * of [0, 0, -1] to [Width, Height, 1] where Width/Height is
+         * the resolution of the screen rendered to. Any spatials
+         * outside of that range are culled.
+         */
+        Gui,
+        
+        /**
+         * A special mode, that will ensure that this spatial uses the same
+         * mode as the parent Node does.
+         */
         Inherit,
     }
 
+    /**
+     * <code>ShadowMode</code> is a marker used to specify how shadow
+     * effects should treat the spatial.
+     */
     public enum ShadowMode {
-
+        /**
+         * Disable both shadow casting and shadow receiving for this spatial.
+         * Generally used for special effects like particle emitters.
+         */
         Off,
+        
+        /**
+         * Enable casting of shadows but not receiving them. 
+         */
         Cast,
+        
+        /**
+         * Enable receiving of shadows but not casting them.
+         */
         Receive,
+        
+        /**
+         * Enable both receiving and casting of shadows.
+         */
         CastAndReceive,
+        
+        /**
+         * Inherit the <code>ShadowMode</code> from the parent node.
+         */
         Inherit
     }
 

engine/src/core/com/jme3/scene/AssetLinkNode.java

@@ -54,6 +54,7 @@ import java.util.logging.Logger;
  * The AssetLinkNode does not store its children when exported to file.
  * Instead, you can add a list of AssetKeys that will be loaded and attached
  * when the AssetLinkNode is restored.
+ * 
  * @author normenhansen
  */
 public class AssetLinkNode extends Node {

engine/src/core/com/jme3/scene/CameraNode.java

@@ -31,7 +31,6 @@
  */
 package com.jme3.scene;
 
-import com.jme3.math.Vector3f;
 import com.jme3.renderer.Camera;
 import com.jme3.scene.control.CameraControl;
 import com.jme3.scene.control.CameraControl.ControlDirection;

engine/src/core/com/jme3/scene/CollisionData.java

@@ -40,7 +40,7 @@ import com.jme3.math.Matrix4f;
 
 /**
  * <code>CollisionData</code> is an interface that can be used to 
- * do triangle-accurate collision between bounding volumes and rays.
+ * do triangle-accurate collision with bounding volumes and rays.
  *
  * @author Kirill Vainer
  */

engine/src/core/com/jme3/scene/Geometry.java

@@ -49,13 +49,18 @@ import java.util.Queue;
 import java.util.logging.Level;
 import java.util.logging.Logger;
 
+/**
+ * <code>Geometry</code> defines a leaf node of the scene graph. The leaf node
+ * contains the geometric data for rendering objects. It manages all rendering
+ * information such as a {@link Material} object to define how the surface
+ * should be shaded and the {@link Mesh} data to contain the actual geometry.
+ * 
+ * @author Kirill Vainer
+ */
 public class Geometry extends Spatial {
 
     private static final Logger logger = Logger.getLogger(Geometry.class.getName());
 
-    /**
-     * The mesh contained herein
-     */
     protected Mesh mesh;
 
     protected transient int lodLevel = 0;
@@ -70,13 +75,16 @@ public class Geometry extends Spatial {
     protected transient Matrix4f cachedWorldMat = new Matrix4f();
 
     /**
-     * Do not use this constructor. Serialization purposes only.
+     * Serialization only. Do not use.
      */
     public Geometry(){
     }
 
     /**
      * Create a geometry node without any mesh data.
+     * Both the mesh and the material are null, the geometry
+     * cannot be rendered until those are set.
+     * 
      * @param name The name of this geometry
      */
     public Geometry(String name){
@@ -85,7 +93,9 @@ public class Geometry extends Spatial {
 
     /**
      * Create a geometry node with mesh data.
-     *
+     * The material of the geometry is null, it cannot
+     * be rendered until it is set.
+     * 
      * @param name The name of this geometry
      * @param mesh The mesh data for this geometry
      */
@@ -99,6 +109,7 @@ public class Geometry extends Spatial {
 
     /**
      * @return If ignoreTransform mode is set.
+     * 
      * @see Geometry#setIgnoreTransform(boolean) 
      */
     public boolean isIgnoreTransform() {
@@ -112,6 +123,14 @@ public class Geometry extends Spatial {
         this.ignoreTransform = ignoreTransform;
     }
 
+    /**
+     * Sets the LOD level to use when rendering the mesh of this geometry.
+     * Level 0 indicates that the default index buffer should be used,
+     * levels [1, LodLevels + 1] represent the levels set on the mesh
+     * with {@link Mesh#setLodLevels(com.jme3.scene.VertexBuffer[]) }.
+     * 
+     * @param lod The lod level to set
+     */
     @Override
     public void setLodLevel(int lod){
         if (mesh.getNumLodLevels() == 0)
@@ -123,35 +142,80 @@ public class Geometry extends Spatial {
         lodLevel = lod;
     }
 
+    /**
+     * Returns the LOD level set with {@link #setLodLevel(int) }.
+     * 
+     * @return the LOD level set
+     */
     public int getLodLevel(){
         return lodLevel;
     }
 
+    /**
+     * Returns this geometry's mesh vertex count.
+     * 
+     * @return this geometry's mesh vertex count.
+     * 
+     * @see Mesh#getVertexCount() 
+     */
     public int getVertexCount(){
         return mesh.getVertexCount();
     }
 
+    /**
+     * Returns this geometry's mesh triangle count.
+     * 
+     * @return this geometry's mesh triangle count.
+     * 
+     * @see Mesh#getTriangleCount() 
+     */
     public int getTriangleCount(){
         return mesh.getTriangleCount();
     }
 
+    /**
+     * Sets the mesh to use for this geometry when rendering.
+     * 
+     * @param mesh the mesh to use for this geometry
+     * 
+     * @throws IllegalArgumentException If mesh is null
+     */
     public void setMesh(Mesh mesh){
         if (mesh == null)
-            throw new NullPointerException();
+            throw new IllegalArgumentException();
 
         this.mesh = mesh;
         setBoundRefresh();
     }
 
+    /**
+     * Returns the mseh to use for this geometry
+     * 
+     * @return the mseh to use for this geometry
+     * 
+     * @see #setMesh(com.jme3.scene.Mesh) 
+     */
     public Mesh getMesh(){
         return mesh;
     }
 
+    /**
+     * Sets the material to use for this geometry.
+     * 
+     * @param material the material to use for this geometry
+     */
     @Override
     public void setMaterial(Material material){
         this.material = material;
     }
 
+    /**
+     * Returns the material that is used for this geometry.
+     * 
+     * @return the material that is used for this geometry
+     * 
+     * @see #setMaterial(com.jme3.material.Material) 
+     */
     public Material getMaterial(){
         return material;
     }
@@ -228,16 +292,26 @@ public class Geometry extends Spatial {
     }
 
     /**
-     * @return A {@link Matrix4f matrix} that transforms the {@link Geometry#getMesh() mesh}
+     * A {@link Matrix4f matrix} that transforms the {@link Geometry#getMesh() mesh}
      * from model space to world space. This matrix is computed based on the
      * {@link Geometry#getWorldTransform() world transform} of this geometry.
      * In order to receive updated values, you must call {@link Geometry#computeWorldMatrix() }
      * before using this method.
+     * 
+     * @return Matrix to transform from local space to world space
      */
     public Matrix4f getWorldMatrix(){
         return cachedWorldMat;
     }
 
+    /**
+     * Sets the model bound to use for this geometry.
+     * This alters the bound used on the mesh as well via
+     * {@link Mesh#setBound(com.jme3.bounding.BoundingVolume) } and
+     * forces the world bounding volume to be recomputed.
+     * 
+     * @param modelBound The model bound to set
+     */
     @Override
     public void setModelBound(BoundingVolume modelBound) {
         this.worldBound = null;

engine/src/core/com/jme3/scene/LightNode.java

@@ -36,7 +36,8 @@ import com.jme3.scene.control.LightControl;
 import com.jme3.scene.control.LightControl.ControlDirection;
 
 /**
- * This Node is a shorthand for using a CameraControl.
+ * <code>LightNode</code> is used to link together a {@link Light} object
+ * with a {@link Node} object. 
  *
  * @author Tim8Dev
  */
@@ -45,7 +46,7 @@ public class LightNode extends Node {
     private LightControl lightControl;
 
     /**
-     * for IO purpose
+     * Serialization only. Do not use.
      */
     public LightNode() {
     }
@@ -60,6 +61,12 @@ public class LightNode extends Node {
         lightControl = control;
     }
 
+    /**
+     * Enable or disable the <code>LightNode</code> functionality.
+     * 
+     * @param enabled If false, the functionality of LightNode will
+     * be disabled.
+     */
     public void setEnabled(boolean enabled) {
         lightControl.setEnabled(enabled);
     }

engine/src/core/com/jme3/scene/Mesh.java

@@ -72,9 +72,13 @@ import java.util.ArrayList;
  * All visible elements in a scene are represented by meshes.
  * Meshes may contain three types of geometric primitives:
  * <ul>
- * <li>Points</li>
+ * <li>Points - Every vertex represents a single point in space, 
- * <li>Lines</li>
+ * the size of each point is specified via {@link Mesh#setPointSize(float) }.
- * <li>Triangles</li>
+ * Points can also be used for {@link RenderState#setPointSprite(boolean) point
+ * sprite} mode.</li>
+ * <li>Lines - 2 vertices represent a line segment, with the width specified
+ * via {@link Mesh#setLineWidth(float) }.</li>
+ * <li>Triangles - 3 vertices represent a solid triangle primitive. </li>
  * </ul>
  * 
  * @author Kirill Vainer

engine/src/core/com/jme3/scene/Node.java

@@ -68,7 +68,7 @@ public class Node extends Spatial implements Savable {
     protected ArrayList<Spatial> children = new ArrayList<Spatial>(1);
 
     /**
-     * Default constructor.
+     * Serialization only. Do not use.
      */
     public Node() {
     }
@@ -141,11 +141,6 @@ public class Node extends Spatial implements Savable {
         this.worldBound = resultBound;
     }
 
-    /**
-     * <code>updateLogicalState</code> updates logic state. Should
-     * be overriden by subclasses desiring this functionality.
-     * @param tpf Time per frame
-     */
     @Override
     public void updateLogicalState(float tpf){
         super.updateLogicalState(tpf);
@@ -159,15 +154,6 @@ public class Node extends Spatial implements Savable {
         }
     }
 
-    /**
-     * <code>updateGeometricState</code> updates all the geometry information
-     * for the node.
-     *
-     * @param time
-     *            the frame time.
-     * @param initiator
-     *            true if this node started the update process.
-     */
     @Override
     public void updateGeometricState(){
         if ((refreshFlags & RF_LIGHTLIST) != 0){
@@ -200,6 +186,7 @@ public class Node extends Spatial implements Savable {
     /**
      * <code>getTriangleCount</code> returns the number of triangles contained
      * in all sub-branches of this node that contain geometry.
+     * 
      * @return the triangle count of this branch.
      */
     @Override
@@ -217,6 +204,7 @@ public class Node extends Spatial implements Savable {
     /**
      * <code>getVertexCount</code> returns the number of vertices contained
      * in all sub-branches of this node that contain geometry.
+     * 
      * @return the vertex count of this branch.
      */
     @Override
@@ -232,7 +220,6 @@ public class Node extends Spatial implements Savable {
     }
 
     /**
-     * 
      * <code>attachChild</code> attaches a child to this node. This node
      * becomes the child's parent. The current number of children maintained is
      * returned.
@@ -305,7 +292,7 @@ public class Node extends Spatial implements Savable {
 
     /**
      * <code>detachChild</code> removes a given child from the node's list.
-     * This child will no longe be maintained.
+     * This child will no longer be maintained.
      * 
      * @param child
      *            the child to remove.
@@ -362,7 +349,7 @@ public class Node extends Spatial implements Savable {
         Spatial child =  children.remove(index);
         if ( child != null ) {
             child.setParent( null );
-            logger.info("Child removed.");
+            logger.log(Level.INFO, "{0}: Child removed.", this.toString());
 
             // since a child with a bound was detached;
             // our own bound will probably change.
@@ -387,17 +374,27 @@ public class Node extends Spatial implements Savable {
         for ( int i = children.size() - 1; i >= 0; i-- ) {
             detachChildAt(i);
         }
-        logger.info("All children removed.");
+        logger.log(Level.INFO, "{0}: All children removed.", this.toString());
     }
 
+    /**
+     * <code>getChildIndex</code> returns the index of the given spatial
+     * in this node's list of children.
+     * @param sp
+     *          The spatial to look up
+     * @return 
+     *          The index of the spatial in the node's children, or -1
+     *          if the spatial is not attached to this node
+     */
     public int getChildIndex(Spatial sp) {
         return children.indexOf(sp);
     }
 
     /**
      * More efficient than e.g detaching and attaching as no updates are needed.
-     * @param index1
+     * 
-     * @param index2
+     * @param index1 The index of the first child to swap
+     * @param index2 The index of the second child to swap
      */
     public void swapChildren(int index1, int index2) {
         Spatial c2 =  children.get(index2);
@@ -467,7 +464,8 @@ public class Node extends Spatial implements Savable {
     }
 
     /**
-     * Returns all children to this node.
+     * Returns all children to this node. Note that modifying that given
+     * list is not allowed.
      *
      * @return a list containing all children to this node
      */

engine/src/core/com/jme3/scene/SceneGraphVisitor.java

@@ -1,9 +1,16 @@
 package com.jme3.scene;
 
 /**
- * Interface to traverse and visit scene graph 
+ * <code>SceneGraphVisitorAdapter</code> is used to traverse the scene
- * by calling Spatial.depthFirstTraversal() or Spatial.breadthFirstTraversal().
+ * graph tree. 
+ * Use by calling {@link Spatial#depthFirstTraversal(com.jme3.scene.SceneGraphVisitor) }
+ * or {@link Spatial#breadthFirstTraversal(com.jme3.scene.SceneGraphVisitor)}.
  */
 public interface SceneGraphVisitor {
+    /**
+     * Called when a spatial is visited in the scene graph.
+     * 
+     * @param spatial The visited spatial
+     */
     public void visit(Spatial spatial);
 }

engine/src/core/com/jme3/scene/SceneGraphVisitorAdapter.java

@@ -1,14 +1,27 @@
 package com.jme3.scene;
 
 /**
- * Traverse and visit Geometry/Node
+ * <code>SceneGraphVisitorAdapter</code> is used to traverse the scene
- * by calling Spatial.depthFirstTraversal() or Spatial.breadthFirstTraversal().
+ * graph tree. The adapter version of the interface simply separates 
- *
+ * between the {@link Geometry geometries} and the {@link Node nodes} by
+ * supplying visit methods that take them.
+ * Use by calling {@link Spatial#depthFirstTraversal(com.jme3.scene.SceneGraphVisitor) }
+ * or {@link Spatial#breadthFirstTraversal(com.jme3.scene.SceneGraphVisitor)}.
  */
 public class SceneGraphVisitorAdapter implements SceneGraphVisitor {
     
+    /**
+     * Called when a {@link Geometry} is visited.
+     * 
+     * @param geom The visited geometry
+     */
     public void visit(Geometry geom) {}
     
+    /**
+     * Called when a {@link visit} is visited.
+     * 
+     * @param geom The visited node
+     */
     public void visit(Node geom) {}
 
     @Override

engine/src/core/com/jme3/scene/Spatial.java

@@ -66,8 +66,8 @@ import java.util.logging.Logger;
 /**
  * <code>Spatial</code> defines the base class for scene graph nodes. It
  * maintains a link to a parent, it's local transforms and the world's
- * transforms. All other nodes, such as <code>Node</code> and
+ * transforms. All other scene graph elements, such as {@link Node} and
- * <code>Geometry</code> are subclasses of <code>Spatial</code>.
+ * {@link Geometry} are subclasses of <code>Spatial</code>.
  *
  * @author Mark Powell
  * @author Joshua Slack
@@ -77,24 +77,30 @@ public abstract class Spatial implements Savable, Cloneable, Collidable {
 
     private static final Logger logger = Logger.getLogger(Spatial.class.getName());
 
+    /**
+     * Specifies how frustum culling should be handled by 
+     * this spatial.
+     */
     public enum CullHint {
-
+        
         /** 
-         * Do whatever our parent does. If no parent, we'll default to dynamic.
+         * Do whatever our parent does. If no parent, default to {@link #Dynamic}.
          */
         Inherit,
         /**
          * Do not draw if we are not at least partially within the view frustum
-         * of the renderer's camera.
+         * of the camera. This is determined via the defined
+         * Camera planes whether or not this Spatial should be culled.
          */
         Dynamic,
         /** 
-         * Always cull this from view.
+         * Always cull this from the view, throwing away this object
+         * and any children from rendering commands.
          */
         Always,
         /**
-         * Never cull this from view. Note that we will still get culled if our
+         * Never cull this from view, always draw it. 
-         * parent is culled.
+         * Note that we will still get culled if our parent is culled.
          */
         Never;
     }
@@ -138,7 +144,7 @@ public abstract class Spatial implements Savable, Cloneable, Collidable {
     protected transient int refreshFlags = 0;
 
     /**
-     * Default Constructor.
+     * Serialization only. Do not use.
      */
     public Spatial() {
         localTransform = new Transform();
@@ -156,7 +162,7 @@ public abstract class Spatial implements Savable, Cloneable, Collidable {
      *
      * @param name
      *            the name of the scene element. This is required for
-     *            identification and comparision purposes.
+     *            identification and comparison purposes.
      */
     public Spatial(String name) {
         this();
@@ -232,12 +238,7 @@ public abstract class Spatial implements Savable, Cloneable, Collidable {
             if (getQueueBucket() == Bucket.Gui) {
                 return cam.containsGui(getWorldBound());
             } else {
-
-//                int state = cam.getPlaneState();
-
                 frustrumIntersects = cam.contains(getWorldBound());
-
-//                cam.setPlaneState(state);
             }
         }
 
@@ -263,10 +264,25 @@ public abstract class Spatial implements Savable, Cloneable, Collidable {
         return name;
     }
 
+    /**
+     * Returns the local {@link LightList}, which are the lights
+     * that were directly attached to this <code>Spatial</code> through the
+     * {@link #addLight(com.jme3.light.Light) } and 
+     * {@link #removeLight(com.jme3.light.Light) } methods.
+     * 
+     * @return The local light list
+     */
     public LightList getLocalLightList() {
         return localLights;
     }
 
+    /**
+     * Returns the world {@link LightList}, containing the lights
+     * combined from all this <code>Spatial's</code> parents up to and including
+     * this <code>Spatial</code>'s lights.
+     * 
+     * @return The combined world light list
+     */
     public LightList getWorldLightList() {
         return worldLights;
     }
@@ -275,7 +291,7 @@ public abstract class Spatial implements Savable, Cloneable, Collidable {
      * <code>getWorldRotation</code> retrieves the absolute rotation of the
      * Spatial.
      *
-     * @return the Spatial's world rotation matrix.
+     * @return the Spatial's world rotation quaternion.
      */
     public Quaternion getWorldRotation() {
         checkDoTransformUpdate();
@@ -286,7 +302,7 @@ public abstract class Spatial implements Savable, Cloneable, Collidable {
      * <code>getWorldTranslation</code> retrieves the absolute translation of
      * the spatial.
      *
-     * @return the world's tranlsation vector.
+     * @return the Spatial's world tranlsation vector.
      */
     public Vector3f getWorldTranslation() {
         checkDoTransformUpdate();
@@ -297,7 +313,7 @@ public abstract class Spatial implements Savable, Cloneable, Collidable {
      * <code>getWorldScale</code> retrieves the absolute scale factor of the
      * spatial.
      *
-     * @return the world's scale factor.
+     * @return the Spatial's world scale factor.
      */
     public Vector3f getWorldScale() {
         checkDoTransformUpdate();
@@ -316,8 +332,8 @@ public abstract class Spatial implements Savable, Cloneable, Collidable {
     }
 
     /**
-     * <code>rotateUpTo</code> is a util function that alters the
+     * <code>rotateUpTo</code> is a utility function that alters the
-     * localrotation to point the Y axis in the direction given by newUp.
+     * local rotation to point the Y axis in the direction given by newUp.
      *
      * @param newUp
      *            the up vector to use - assumed to be a unit vector.
@@ -350,11 +366,11 @@ public abstract class Spatial implements Savable, Cloneable, Collidable {
     }
 
     /**
-     * <code>lookAt</code> is a convienence method for auto-setting the local
+     * <code>lookAt</code> is a convenience method for auto-setting the local
      * rotation based on a position and an up vector. It computes the rotation
      * to transform the z-axis to point onto 'position' and the y-axis to 'up'.
-     * Unlike {@link Quaternion#lookAt} this method takes a world position to
+     * Unlike {@link Quaternion#lookAt(com.jme3.math.Vector3f, com.jme3.math.Vector3f) } 
-     * look at not a relative direction.
+     * this method takes a world position to look at and not a relative direction.
      *
      * @param position
      *            where to look at in terms of world coordinates
@@ -377,7 +393,7 @@ public abstract class Spatial implements Savable, Cloneable, Collidable {
     }
 
     /**
-     * Should be overriden by Node and Geometry.
+     * Should be overridden by Node and Geometry.
      */
     protected void updateWorldBound() {
         // the world bound of a leaf is the same as it's model bound
@@ -418,6 +434,10 @@ public abstract class Spatial implements Savable, Cloneable, Collidable {
         }
     }
 
+    /**
+     * Computes the world transform of this Spatial in the most 
+     * efficient manner possible.
+     */
     void checkDoTransformUpdate() {
         if ((refreshFlags & RF_TRANSFORM) == 0) {
             return;
@@ -464,6 +484,10 @@ public abstract class Spatial implements Savable, Cloneable, Collidable {
         }
     }
 
+    /**
+     * Computes this Spatial's world bounding volume in the most efficient
+     * manner possible.
+     */
     void checkDoBoundUpdate() {
         if ((refreshFlags & RF_BOUND) == 0) {
             return;
@@ -675,7 +699,7 @@ public abstract class Spatial implements Savable, Cloneable, Collidable {
     }
 
     /**
-     * <code>getParent</code> retrieve's this node's parent. If the parent is
+     * <code>getParent</code> retrieves this node's parent. If the parent is
      * null this is the root node.
      *
      * @return the parent of this node.
@@ -737,7 +761,8 @@ public abstract class Spatial implements Savable, Cloneable, Collidable {
     }
 
     /**
-     * <code>setLocalRotation</code> sets the local rotation of this node.
+     * <code>setLocalRotation</code> sets the local rotation of this node
+     * by using a {@link Matrix3f}.
      *
      * @param rotation
      *            the new local rotation.
@@ -749,11 +774,10 @@ public abstract class Spatial implements Savable, Cloneable, Collidable {
     }
 
     /**
-     * <code>setLocalRotation</code> sets the local rotation of this node,
+     * <code>setLocalRotation</code> sets the local rotation of this node.
-     * using a quaterion to build the matrix.
      *
      * @param quaternion
-     *            the quaternion that defines the matrix.
+     *            the new local rotation.
      */
     public void setLocalRotation(Quaternion quaternion) {
         localTransform.setRotation(quaternion);
@@ -1261,13 +1285,8 @@ public abstract class Spatial implements Savable, Cloneable, Collidable {
 
     /**
      * <code>setCullHint</code> sets how scene culling should work on this
-     * spatial during drawing. CullHint.Dynamic: Determine via the defined
+     * spatial during drawing. NOTE: You must set this AFTER attaching to a 
-     * Camera planes whether or not this Spatial should be culled.
+     * parent or it will be reset with the parent's cullMode value.
-     * CullHint.Always: Always throw away this object and any children during
-     * draw commands. CullHint.Never: Never throw away this object (always draw
-     * it) CullHint.Inherit: Look for a non-inherit parent and use its cull
-     * mode. NOTE: You must set this AFTER attaching to a parent or it will be
-     * reset with the parent's cullMode value.
      *
      * @param hint
      *            one of CullHint.Dynamic, CullHint.Always, CullHint.Inherit or
@@ -1286,21 +1305,10 @@ public abstract class Spatial implements Savable, Cloneable, Collidable {
 
     /**
      * <code>setQueueBucket</code> determines at what phase of the
-     * rendering proces this Spatial will rendered. There are 4 different
+     * rendering process this Spatial will rendered. See the
-     * phases: Bucket.Opaque - The renderer will
+     * {@link Bucket} enum for an explanation of the various 
-     * try to find the optimal order for rendering all objects using this mode.
+     * render queue buckets.
-     * You should use this mode for most normal objects, except transparant
+     * 
-     * ones, as it could give a nice performance boost to your application.
-     * Bucket.Transparent - This is the mode you should use for object with
-     * transparancy in them. It will ensure the objects furthest away are
-     * rendered first. That ensures when another transparent object is drawn on
-     * top of previously drawn objects, you can see those (and the object drawn
-     * using Opaque) through the tranparant parts of the newly drawn
-     * object. Bucket.Gui - This is a special mode, for drawing 2D object
-     * without prespective (such as GUI or HUD parts) Lastly, there is a special
-     * mode, Bucket.Inherit, that will ensure that this spatial uses the same
-     * mode as the parent Node does.
-     *
      * @param queueBucket
      *            The bucket to use for this Spatial.
      */
@@ -1312,7 +1320,7 @@ public abstract class Spatial implements Savable, Cloneable, Collidable {
      * Sets the shadow mode of the spatial
      * The shadow mode determines how the spatial should be shadowed,
      * when a shadowing technique is used. See the
-     * documentation for the class ShadowMode for more information.
+     * documentation for the class {@link ShadowMode} for more information.
      *
      * @see ShadowMode
      *
@@ -1355,8 +1363,7 @@ public abstract class Spatial implements Savable, Cloneable, Collidable {
     /**
      * Overrides the last intersection result. This is useful for operations
      * that want to start rendering at the middle of a scene tree and don't want
-     * the parent of that node to influence culling. (See texture renderer code
+     * the parent of that node to influence culling.
-     * for example.)
      *
      * @param intersects
      *            the new value

engine/src/core/com/jme3/scene/UserData.java

@@ -38,6 +38,13 @@ import com.jme3.export.OutputCapsule;
 import com.jme3.export.Savable;
 import java.io.IOException;
 
+/**
+ * <code>UserData</code> is used to contain user data objects
+ * set on spatials (primarily primitives) that do not implement
+ * the {@link Savable} interface. Note that attempting
+ * to export any models which have non-savable objects
+ * attached to them will fail.
+ */
 public final class UserData implements Savable {
 
     protected byte type;
@@ -46,6 +53,13 @@ public final class UserData implements Savable {
     public UserData() {
     }
 
+    /**
+     * Creates a new <code>UserData</code> with the given 
+     * type and value.
+     * 
+     * @param type Type of data, should be between 0 and 4.
+     * @param value Value of the data
+     */
     public UserData(byte type, Object value) {
         assert type >= 0 && type <= 4;
         this.type = type;

engine/src/core/com/jme3/scene/VertexBuffer.java

@@ -52,6 +52,15 @@ import java.nio.ShortBuffer;
  * A <code>VertexBuffer</code> contains a particular type of geometry
  * data used by {@link Mesh}es. Every VertexBuffer set on a <code>Mesh</code>
  * is sent as an attribute to the vertex shader to be processed.
+ * <p>
+ * Several terms are used throughout the javadoc for this class, explanation:
+ * <ul>
+ * <li>Element - A single element is the largest individual object
+ * inside a VertexBuffer. E.g. if the VertexBuffer is used to store 3D position
+ * data, then an element will be a single 3D vector.</li>
+ * <li>Component - A component represents the parts inside an element. 
+ * For a 3D vector, a single component is one of the dimensions, X, Y or Z.</li>
+ * </ul>
  */
 public class VertexBuffer extends GLObject implements Savable, Cloneable {
 
@@ -65,17 +74,17 @@ public class VertexBuffer extends GLObject implements Savable, Cloneable {
         Position,
 
         /**
-         * The size of the point when using point buffers.
+         * The size of the point when using point buffers (float).
          */
         Size,
 
         /**
-         * Normal vector, normalized.
+         * Normal vector, normalized (3 floats).
          */
         Normal,
 
         /**
-         * Texture coordinate
+         * Texture coordinate (2 float)
          */
         TexCoord,
 
@@ -85,18 +94,19 @@ public class VertexBuffer extends GLObject implements Savable, Cloneable {
         Color,
 
         /**
-         * Tangent vector, normalized.
+         * Tangent vector, normalized (3 floats)
          */
         Tangent,
 
         /**
-         * Binormal vector, normalized.
+         * Binormal vector, normalized (3 floats, optional)
          */
         Binormal,
 
         /**
          * Specifies the source data for various vertex buffers
-         * when interleaving is used.
+         * when interleaving is used. By default the format is
+         * byte.
          */
         InterleavedData,
 
@@ -107,27 +117,42 @@ public class VertexBuffer extends GLObject implements Savable, Cloneable {
         MiscAttrib,
 
         /**
-         * Specifies the index buffer, must contain integer data.
+         * Specifies the index buffer, must contain integer data
+         * (ubyte, ushort, or uint).
          */
         Index,
 
         /** 
-         * Inital vertex position, used with animation 
+         * Initial vertex position, used with animation.
+         * Should have the same format and size as {@link Type#Position}.
+         * If used with software skinning, the usage should be 
+         * {@link Usage#CpuOnly}, and the buffer should be allocated
+         * on the heap.
          */
         BindPosePosition,
 
         /** 
-         * Inital vertex normals, used with animation
+         * Initial vertex normals, used with animation.
+         * Should have the same format and size as {@link Type#Normal}.
+         * If used with software skinning, the usage should be 
+         * {@link Usage#CpuOnly}, and the buffer should be allocated
+         * on the heap.
          */
         BindPoseNormal,
 
         /** 
-         * Bone weights, used with animation
+         * Bone weights, used with animation (4 floats).
+         * If used with software skinning, the usage should be 
+         * {@link Usage#CpuOnly}, and the buffer should be allocated
+         * on the heap.
          */
         BoneWeight,
 
         /** 
-         * Bone indices, used with animation
+         * Bone indices, used with animation (4 ubytes).
+         * If used with software skinning, the usage should be 
+         * {@link Usage#CpuOnly}, and the buffer should be allocated
+         * on the heap.
          */
         BoneIndex,
 
@@ -190,24 +215,68 @@ public class VertexBuffer extends GLObject implements Savable, Cloneable {
         Stream,
 
         /**
-         * Mesh data is not sent to GPU at all. It is only
+         * Mesh data is <em>not</em> sent to GPU at all. It is only
          * used by the CPU.
          */
         CpuOnly;
     }
 
+    /**
+     * Specifies format of the data stored in the buffer.
+     * This should directly correspond to the buffer's class, for example,
+     * an {@link Format#UnsignedShort} formatted buffer should use the
+     * class {@link ShortBuffer} (e.g. the closest resembling type).
+     * For the {@link Format#Half} type, {@link ByteBuffer}s should
+     * be used.
+     */
     public static enum Format {
-        // Floating point formats
+        /**
+         * Half precision floating point.
+         * 2 bytes, signed.
+         */
         Half(2),
+        
+        /**
+         * Single precision floating point.
+         * 4 bytes, signed
+         */
         Float(4),
+        
+        /**
+         * Double precision floating point.
+         * 8 bytes, signed. May not
+         * be supported by all GPUs.
+         */
         Double(8),
 
-        // Integer formats
+        /**
+         * 1 byte integer, signed.
+         */
         Byte(1),
+        
+        /**
+         * 1 byte integer, unsigned.
+         */
         UnsignedByte(1),
+        
+        /**
+         * 2 byte integer, signed.
+         */
         Short(2),
+        
+        /**
+         * 2 byte integer, unsigned.
+         */
         UnsignedShort(2),
+        
+        /**
+         * 4 byte integer, signed.
+         */
         Int(4),
+        
+        /**
+         * 4 byte integer, unsigned.
+         */
         UnsignedInt(4);
 
         private int componentSize = 0;
@@ -217,6 +286,8 @@ public class VertexBuffer extends GLObject implements Savable, Cloneable {
         }
 
         /**
+         * Returns the size in bytes of this data type.
+         * 
          * @return Size in bytes of this data type.
          */
         public int getComponentSize(){
@@ -250,7 +321,7 @@ public class VertexBuffer extends GLObject implements Savable, Cloneable {
     }
 
     /**
-     * Do not use this constructor. Serialization purposes only.
+     * Serialization only. Do not use.
      */
     public VertexBuffer(){
         super(GLObject.Type.VertexBuffer);
@@ -261,8 +332,9 @@ public class VertexBuffer extends GLObject implements Savable, Cloneable {
     }
 
     /**
-     * @return The offset (in bytes) from the start of the buffer
+     * @return The offset after which the data is sent to the GPU.
-     * after which the data is sent to the GPU.
+     * 
+     * @see #setOffset(int) 
      */
     public int getOffset() {
         return offset;
@@ -277,20 +349,22 @@ public class VertexBuffer extends GLObject implements Savable, Cloneable {
     }
 
     /**
-     * @return The stride (in bytes) for the data. If the data is packed
+     * @return The stride (in bytes) for the data. 
-     * in the buffer, then stride is 0, if there's other data that is between
+     * 
-     * the current component and the next component in the buffer, then this
+     * @see #setStride(int) 
-     * specifies the size in bytes of that additional data.
      */
     public int getStride() {
         return stride;
     }
 
     /**
-     * @param stride The stride (in bytes) for the data. If the data is packed
+     * Set the stride (in bytes) for the data. 
-     * in the buffer, then stride is 0, if there's other data that is between
+     * <p>
-     * the current component and the next component in the buffer, then this
+     * If the data is packed in the buffer, then stride is 0, if there's other 
-     * specifies the size in bytes of that additional data.
+     * data that is between the current component and the next component in the 
+     * buffer, then this specifies the size in bytes of that additional data.
+     * 
+     * @param stride the stride (in bytes) for the data
      */
     public void setStride(int stride) {
         this.stride = stride;
@@ -432,6 +506,11 @@ public class VertexBuffer extends GLObject implements Savable, Cloneable {
         setUpdateNeeded();
     }
 
+    /**
+     * Returns true if the data size of the VertexBuffer has changed.
+     * Internal use only.
+     * @return true if the data size has changed
+     */
     public boolean hasDataSizeChanged() {
         return dataSizeChanged;
     }
@@ -477,7 +556,7 @@ public class VertexBuffer extends GLObject implements Savable, Cloneable {
      * of elements, any elements at the end of the buffer are truncated
      * as necessary.
      *
-     * @param numElements
+     * @param numElements The number of elements to reduce to.
      */
     public void compact(int numElements){
         int total = components * numElements;
@@ -523,6 +602,16 @@ public class VertexBuffer extends GLObject implements Savable, Cloneable {
         dataSizeChanged = true;
     }
 
+    /**
+     * Modify a component inside an element.
+     * The <code>val</code> parameter must be in the buffer's format:
+     * {@link Format}.
+     * 
+     * @param elementIndex The element index to modify
+     * @param componentIndex The component index to modify
+     * @param val The value to set, either byte, short, int or float depending
+     * on the {@link Format}.
+     */
     public void setElementComponent(int elementIndex, int componentIndex, Object val){
         int inPos = elementIndex * components;
         int elementPos = componentIndex;
@@ -560,6 +649,14 @@ public class VertexBuffer extends GLObject implements Savable, Cloneable {
         }
     }
 
+    /**
+     * Get the component inside an element.
+     * 
+     * @param elementIndex The element index
+     * @param componentIndex The component index
+     * @return The component, as one of the primitive types, byte, short,
+     * int or float.
+     */
     public Object getElementComponent(int elementIndex, int componentIndex){
         int inPos = elementIndex * components;
         int elementPos = componentIndex;
@@ -597,9 +694,12 @@ public class VertexBuffer extends GLObject implements Savable, Cloneable {
      * Copies a single element of data from this <code>VertexBuffer</code>
      * to the given output VertexBuffer.
      * 
-     * @param inIndex
+     * @param inIndex The input element index
-     * @param outVb
+     * @param outVb The buffer to copy to
-     * @param outIndex
+     * @param outIndex The output element index
+     * 
+     * @throws IllegalArgumentException If the formats of the buffers do not
+     * match.
      */
     public void copyElement(int inIndex, VertexBuffer outVb, int outIndex){
         if (outVb.format != format || outVb.components != components)
@@ -692,6 +792,11 @@ public class VertexBuffer extends GLObject implements Savable, Cloneable {
         }
     }
 
+    /**
+     * Creates a deep clone of the {@link VertexBuffer}.
+     * 
+     * @return Deep clone of this buffer
+     */
     @Override
     public VertexBuffer clone(){
         // NOTE: Superclass GLObject automatically creates shallow clone
@@ -705,6 +810,13 @@ public class VertexBuffer extends GLObject implements Savable, Cloneable {
         return vb;
     }
 
+    /**
+     * Creates a deep clone of this VertexBuffer but overrides the
+     * {@link Type}.
+     * 
+     * @param overrideType The type of the cloned VertexBuffer
+     * @return A deep clone of the buffer
+     */
     public VertexBuffer clone(Type overrideType){
         VertexBuffer vb = new VertexBuffer(overrideType);
         vb.components = components;

engine/src/core/com/jme3/scene/control/Control.java

@@ -39,6 +39,9 @@ import com.jme3.scene.Spatial;
 
 /**
  * An interface for scene-graph controls. 
+ * <p>
+ * <code>Control</code>s are used to specify certain update and render logic
+ * for a {@link Spatial}. 
  *
  * @author Kirill Vainer
  */

engine/src/core/com/jme3/scene/control/LodControl.java

@@ -67,23 +67,52 @@ public class LodControl extends AbstractControl implements Cloneable {
     private int[] numTris;
 
     /**
-     * Serialization only. Do not use.
+     * Creates a new <code>LodControl</code>.
      */
     public LodControl(){
     }
 
+    /**
+     * Returns the distance tolerance for changing LOD.
+     * 
+     * @return the distance tolerance for changing LOD.
+     * 
+     * @see #setDistTolerance(float) 
+     */
     public float getDistTolerance() {
         return distTolerance;
     }
 
+    /**
+     * Specifies the distance tolerance for changing the LOD level on the geometry.
+     * The LOD level will only get changed if the geometry has moved this 
+     * distance beyond the current LOD level.
+     * 
+     * @param distTolerance distance tolerance for changing LOD
+     */
     public void setDistTolerance(float distTolerance) {
         this.distTolerance = distTolerance;
     }
 
+    /**
+     * Returns the triangles per pixel value.
+     * 
+     * @return the triangles per pixel value.
+     * 
+     * @see #setTrisPerPixel(float) 
+     */
     public float getTrisPerPixel() {
         return trisPerPixel;
     }
 
+    /**
+     * Sets the triangles per pixel value.
+     * The <code>LodControl</code> will use this value as an error metric
+     * to determine which LOD level to use based on the geometry's
+     * area on the screen.
+     * 
+     * @param trisPerPixel triangles per pixel
+     */
     public void setTrisPerPixel(float trisPerPixel) {
         this.trisPerPixel = trisPerPixel;
     }