MPO: add javadoc

jme3-core/src/main/java/com/jme3/material/MatParam.java

@@ -34,7 +34,6 @@ package com.jme3.material;
 import com.jme3.asset.TextureKey;
 import com.jme3.export.*;
 import com.jme3.math.*;
-import com.jme3.renderer.Renderer;
 import com.jme3.shader.VarType;
 import com.jme3.texture.Texture;
 import com.jme3.texture.Texture.WrapMode;

jme3-core/src/main/java/com/jme3/material/MatParamOverride.java

@@ -31,16 +31,71 @@
  */
 package com.jme3.material;
 
+import com.jme3.export.InputCapsule;
+import com.jme3.export.JmeExporter;
+import com.jme3.export.JmeImporter;
+import com.jme3.export.OutputCapsule;
+import com.jme3.scene.Spatial;
 import com.jme3.shader.VarType;
+import java.io.IOException;
 
+/**
+ * <code>MatParamOverride</code> is a mechanism by which
+ * {@link MatParam material parameters} can be overridden on the scene graph.
+ * <p>
+ * A scene branch which has a <code>MatParamOverride</code> applied to it will
+ * cause all material parameters with the same name and type to have their value
+ * replaced with the value set on the <code>MatParamOverride</code>. If those
+ * parameters are mapped to a define, then the define will be overridden as well
+ * using the same rules as the ones used for regular material parameters.
+ * <p>
+ * <code>MatParamOverrides</code> are applied to a {@link Spatial} via the
+ * {@link Spatial#addMatParamOverride(com.jme3.material.MatParamOverride)}
+ * method. They are propagated to child <code>Spatials</code> via
+ * {@link Spatial#updateGeometricState()} similar to how lights are propagated.
+ * <p>
+ * Example:<br>
+ * <pre>
+ * {@code
+ *
+ * Geometry box = new Geometry("Box", new Box(1,1,1));
+ * Material mat = new Material(assetManager, "Common/MatDefs/Misc/Unshaded.j3md");
+ * mat.setColor("Color", ColorRGBA.Blue);
+ * box.setMaterial(mat);
+ * rootNode.attachChild(box);
+ *
+ * // ... later ...
+ * MatParamOverride override = new MatParamOverride(Type.Vector4, "Color", ColorRGBA.Red);
+ * rootNode.addMatParamOverride(override);
+ *
+ * // After adding the override to the root node, the box becomes red.
+ * }
+ * </pre>
+ *
+ * @author Kirill Vainer
+ * @see Spatial#addMatParamOverride(com.jme3.material.MatParamOverride)
+ * @see Spatial#getWorldMatParamOverrides()
+ */
 public final class MatParamOverride extends MatParam {
 
     private boolean enabled = true;
 
+    /**
+     * Serialization only. Do not use.
+     */
     public MatParamOverride() {
         super();
     }
 
+    /**
+     * Create a new <code>MatParamOverride</code>.
+     *
+     * Overrides are created enabled by default.
+     *
+     * @param type The type of parameter.
+     * @param name The name of the parameter.
+     * @param value The value to set the material parameter to.
+     */
     public MatParamOverride(VarType type, String name, Object value) {
         super(type, name, value);
     }
@@ -56,10 +111,26 @@ public final class MatParamOverride extends MatParam {
         hash = 59 * hash + (enabled ? 1 : 0);
         return hash;
     }
+
+    /**
+     * Determine if the <code>MatParamOverride</code> is enabled or disabled.
+     *
+     * @return true if enabled, false if disabled.
+     * @see #setEnabled(boolean)
+     */
     public boolean isEnabled() {
         return enabled;
     }
 
+    /**
+     * Enable or disable this <code>MatParamOverride</code>.
+     *
+     * When disabled, the override will continue to propagate through the scene
+     * graph like before, but it will have no effect on materials. Overrides are
+     * enabled by default.
+     *
+     * @param enabled Whether to enable or disable this override.
+     */
     public void setEnabled(boolean enabled) {
         this.enabled = enabled;
     }

jme3-core/src/main/java/com/jme3/scene/Spatial.java

@@ -607,12 +607,23 @@ public abstract class Spatial implements Savable, Cloneable, Collidable, Cloneab
         setMatParamOverrideRefresh();
     }
 
+    /**
+     * Remove a local material parameter override if it exists.
+     *
+     * @param override The override to remove.
+     * @see MatParamOverride
+     */
     public void removeMatParamOverride(MatParamOverride override) {
         if (localOverrides.remove(override)) {
             setMatParamOverrideRefresh();
         }
     }
 
+    /**
+     * Remove all local material parameter overrides.
+     *
+     * @see #addMatParamOverride(com.jme3.material.MatParamOverride)
+     */
     public void clearMatParamOverrides() {
         if (!localOverrides.isEmpty()) {
             setMatParamOverrideRefresh();

jme3-core/src/test/java/com/jme3/material/MaterialMatParamOverrideTest.java

@@ -55,6 +55,11 @@ import com.jme3.texture.Texture2D;
 import java.util.HashMap;
 import java.util.Map;
 
+/**
+ * Validates how {@link MatParamOverride MPOs} work on the material level.
+ *
+ * @author Kirill Vainer
+ */
 public class MaterialMatParamOverrideTest {
 
     private static final HashSet<String> IGNORED_UNIFORMS = new HashSet<String>(

jme3-core/src/test/java/com/jme3/scene/SceneMatParamOverrideTest.java

@@ -43,7 +43,11 @@ import com.jme3.system.TestUtil;
 import java.util.ArrayList;
 import java.util.List;
 
-
+/**
+ * Validates how {@link MatParamOverride MPOs} work on the scene level.
+ *
+ * @author Kirill Vainer
+ */
 public class SceneMatParamOverrideTest {
 
     private static Node createDummyScene() {