--- a/gnv-artifacts/src/main/java/de/intevation/gnv/math/Point2d.java	Tue Apr 06 07:01:03 2010 +0000
+++ b/gnv-artifacts/src/main/java/de/intevation/gnv/math/Point2d.java	Tue Apr 06 11:05:00 2010 +0000
@@ -8,15 +8,23 @@
 import org.apache.log4j.Logger;
 
 /**
- *  @author <a href="mailto:sascha.teichmann@intevation.de">Sascha L. Teichmann</a>
+ * Point which besides the x, y, z coodinates has an index i, j pair
+ * to model neighborhood.
+ * @author <a href="mailto:sascha.teichmann@intevation.de">Sascha L. Teichmann</a>
  */
 public class Point2d
 extends      Coordinate
 {
     private static Logger log = Logger.getLogger(Point2d.class);
 
+    /**
+     * Numerical tolerance epsilon: {@value}
+     */
     public static final double EPSILON = 1e-3d;
 
+    /**
+     * Compares two Point2ds by their x coordinates
+     */
     public static final Comparator X_COMPARATOR = new Comparator() {
         public int compare(Object a, Object b) {
             double xa = ((Coordinate)a).x;
@@ -27,6 +35,9 @@
         }
     };
 
+    /**
+     * Compares two Point2ds by their y coordinates.
+     */
     public static final Comparator Y_COMPARATOR = new Comparator() {
         public int compare(Object a, Object b) {
             double ya = ((Coordinate)a).y;
@@ -37,75 +48,116 @@
         }
     };
 
-    public static class InverseL1Comparator
-    implements          Comparator
-    {
-        private Point2d ref;
-
-        public InverseL1Comparator(Point2d ref) {
-            this.ref = ref;
-        }
-
-        public int compare(Object a, Object b) {
-            Point2d pa = (Point2d)a;
-            Point2d pb = (Point2d)b;
-            double da = ref.L1(pa);
-            double db = ref.L1(pb);
-            if (da < db) return -1;
-            if (da > db) return +1;
-            return 0;
-        }
-    } // class InverseL1Comparator
-
+    /**
+     * The i index of this Point2d.
+     */
     public int i;
+    /**
+     * The j index of this Point2d.
+     */
     public int j;
 
+    /**
+     * Default constructor.
+     */
     public Point2d() {
     }
 
+    /**
+     * Constructor setting x and y coordinate.
+     * @param x The x coordinate.
+     * @param y The y coordinate.
+     */
     public Point2d(double x, double y) {
         super(x, y);
     }
 
+    /**
+     * Constructor setting x, y and i, j.
+     * @param x The x coordinate.
+     * @param y The y coordinate.
+     * @param i The i index.
+     * @param j The j index.
+     */
     public Point2d(double x, double y, int i, int j) {
         super(x, y);
         this.i = i;
         this.j = j;
     }
 
+    /**
+     * Constructor setting x, y, z and i, j.
+     * @param x The x coordinate.
+     * @param y The y coordinate.
+     * @param z The z coordinate.
+     * @param i The i index.
+     * @param j The j index.
+     */
     public Point2d(double x, double y, double z, int i, int j) {
         super(x, y, z);
         this.i = i;
         this.j = j;
     }
 
-
+    /**
+     * Calculates the L1 distance to another Point2d.
+     * @param other The other Point2d.
+     * @return The L1 distance.
+     */
     public double L1(Point2d other) {
-        return L1(this, other);
+        return L1Comparator.L1(this, other);
     }
 
-    public static double L1(Coordinate a, Coordinate b) {
-        return Math.abs(a.x - b.x) + Math.abs(a.y - b.y);
-    }
-
+    /**
+     * Creates an envelope around this Point2d with
+     * the numerical tolerance of {@link #EPSILON}.
+     * @return The envelope.
+     */
     public Envelope envelope() {
         return envelope(EPSILON);
     }
 
+    /**
+     *Creates an envelope around this Point2d with
+     * a given tolerance.
+     * @param epsilon The tolerance in all directions.
+     * @return The envelope.
+     */
     public Envelope envelope(double epsilon) {
         return new Envelope(
             x-epsilon, x+epsilon,
             y-epsilon, y+epsilon);
     }
 
+    /**
+     * Given this and another Point2d it looks if there is
+     * a gap between the in points in i index direction.
+     * @param other The other Point2d.
+     * @return true if there is is a gap, else false.
+     */
     public boolean hasIGap(Point2d other) {
         return Math.abs(i - other.i) > 1;
     }
 
+    /**
+     * Given this and another Point2d it looks if there is
+     * a gap between the in points in j index direction.
+     * @param other The other Point2d.
+     * @return true if there is is a gap, else false.
+     */
     public boolean hasJGap(Point2d other) {
         return Math.abs(j - other.j) > 1;
     }
 
+    /**
+     * Given this and another Point2d a new Point2d is
+     * created via {@link #newPoint() }. The x, y coordinate
+     * of the new point is on the line of this and the other
+     * given point at a given scaling point.
+     * @param t The scaling factor.
+     * @param other The other point.
+     * @return The new Point2d.
+     */
     public Point2d extrapolate(double t, Point2d other) {
         if (other == null) {
             return null;
@@ -116,14 +168,33 @@
         return p;
     }
 
+    /**
+     * Creates a new Point2d or an instance of a subclass.
+     * Override this in subclasses.
+     * @return The new Point2d.
+     */
     public Point2d newPoint() {
         return new Point2d(0d, 0d);
     }
 
+    /**
+     * Creates a new Point2d or an instance of a subclass
+     * at a given coordinate.
+     * Override this in subclasses.
+     * @param x The x coordinate.
+     * @param y The y coordinate.
+     * @return The new point.
+     */
     public Point2d newPoint(double x, double y) {
         return new Point2d(x, y);
     }
 
+    /**
+     * Sets the z value to the inverse distance weighting (IDW) value
+     * of the z values of a set of given points.
+     * @param ps The points from wich the z values are taken
+     * to calculate the IDW.
+     */
     public void inverseDistanceWeighting(Point2d [] ps) {
 
         double sum = 0d;
@@ -156,6 +227,14 @@
         z = v/sum;
     }
 
+    /**
+     * Creates a new point via {@link #newPoint() } with the
+     * x,y coordinates of the center of a given set of
+     * coordinates.
+     * @param ps The points from which the x,y coordinates are
+     * taken to calculate the center.
+     * @return The new center point.
+     */
     public static Point2d average(Point2d [] ps) {
 
         Point2d p = null;
@@ -184,6 +263,14 @@
         return p;
     }
 
+    /**
+     * Checks if this Point2d is near to at least one point
+     * out of a given set of points. Near is defined by an
+     * euclidian distance small than {@link #EPSILON}.
+     * @param ps The set of points to be tested.
+     * @return true if this Point2d is near to one of the given
+     * points, else false.
+     */
     public boolean near(Point2d [] ps) {
 
         for (int i = 0; i < ps.length; ++i) {
@@ -196,4 +283,4 @@
         return true;
     }
 }
-// vim:set ts=4 sw=4 si et sta sts=4 fenc=utf8:
+// vim:set ts=4 sw=4 si et sta sts=4 fenc=utf8 :