fixed findbugs warnings and added more explanation about the corresponding behavior in javadoc

git-svn-id: https://svn.apache.org/repos/asf/commons/proper/math/trunk@762136 13f79535-47bb-0310-9956-ffa450edef68

findbugs-exclude-filter.xml

@@ -84,6 +84,11 @@
     </Or>
     <Bug pattern="EI_EXPOSE_REP" />
   </Match>
+  <Match>
+    <Class name="org.apache.commons.math.ode.sampling.MultistepStepInterpolator"/>
+    <Method name="reinitialize" params="double[],double[],double[][],boolean" returns="void" />
+    <Bug pattern="EI_EXPOSE_REP2" />
+  </Match>
   <Match>
     <Class name="org.apache.commons.math.linear.BigMatrixImpl"/>
     <Method name="&lt;init>" params="java.math.BigDecimal[][],boolean" returns="void" />

src/java/org/apache/commons/math/ode/sampling/MultistepStepInterpolator.java

@@ -93,6 +93,8 @@ public abstract class MultistepStepInterpolator
     }
 
     /** Reinitialize the instance
+     * <p>Beware that all arrays <em>must</em> be references to integrator
+     * arrays, in order to ensure proper update without copy.</p>
      * @param y reference to the integrator array holding the state at
      * the end of the step
      * @param previousT reference to the integrator array holding the times

src/java/org/apache/commons/math/ode/sampling/StepInterpolator.java

@@ -32,6 +32,14 @@ import org.apache.commons.math.ode.SecondOrderIntegrator;
  * handlers can use these objects to retrieve the state vector at
  * intermediate times between the previous and the current grid points
  * (this feature is often called dense output).</p>
+ * <p>One important thing to note is that the step handlers may be so
+ * tightly bound to the integrators that they often share some internal
+ * state arrays. This imply that one should <em>never</em> use a direct
+ * reference to a step interpolator outside of the step handler, either
+ * for future use or for use in another thread. If such a need arise, the
+ * step interpolator <em>must</em> be copied using the dedicated
+ * {@link #copy()} method.
+ * </p>
  *
  * @see FirstOrderIntegrator
  * @see SecondOrderIntegrator