added comments in the code to explain use of real number equality tests

JIRA: MATH-183

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

src/java/org/apache/commons/math/analysis/BrentSolver.java

@@ -202,6 +202,9 @@ public class BrentSolver extends UnivariateRealSolverImpl {
                 double r3 = y1 / y0;
                 double p;
                 double p1;
+                // the equality test (x0 == x2) is intentional,
+                // it is part of the original Brent's method,
+                // it should NOT be replaced by proximity test
                 if (x0 == x2) {
                     // Linear interpolation.
                     p = dx * r3;

src/java/org/apache/commons/math/analysis/MullerSolver.java

@@ -153,6 +153,8 @@ public class MullerSolver extends UnivariateRealSolverImpl {
 
             // Bisect if convergence is too slow. Bisection would waste
             // our calculation of x, hopefully it won't happen often.
+            // the real number equality test x == x1 is intentional and
+            // completes the proximity tests above it
             boolean bisect = (x < x1 && (x1 - x0) > 0.95 * (x2 - x0)) ||
                              (x > x1 && (x2 - x1) > 0.95 * (x2 - x0)) ||
                              (x == x1);
@@ -244,7 +246,8 @@ public class MullerSolver extends UnivariateRealSolverImpl {
             }
             if (denominator != 0) {
                 x = x2 - 2.0 * C * (x2 - x1) / denominator;
-                // perturb x if it coincides with x1 or x2
+                // perturb x if it exactly coincides with x1 or x2
+                // the equality tests here are intentional
                 while (x == x1 || x == x2) {
                     x += absoluteAccuracy;
                 }

src/java/org/apache/commons/math/util/MathUtils.java

@@ -784,6 +784,7 @@ public final class MathUtils {
             } else if (fraction < 0.5) {
                 unscaled = Math.floor(unscaled);
             } else {
+                // The following equality test is intentional and needed for rounding purposes
                 if (Math.floor(unscaled) / 2.0 == Math.floor(Math
                     .floor(unscaled) / 2.0)) { // even
                     unscaled = Math.floor(unscaled);