--- a/gnv-artifacts/src/main/java/de/intevation/gnv/math/LinearToMap.java	Thu Apr 08 10:10:04 2010 +0000
+++ b/gnv-artifacts/src/main/java/de/intevation/gnv/math/LinearToMap.java	Thu Apr 08 11:31:44 2010 +0000
@@ -7,10 +7,18 @@
 import java.util.NoSuchElementException;
 
 /**
+ * Given a list of line segments instances of this class are able
+ * to span a metric system between a start and an end point
+ * represented as scalar values to 2D coordinate on the
+ * course of the segments.
+ *
  * @author <a href="mailto:sascha.teichmann@intevation.de">Sascha L. Teichmann</a>
  */
 public class LinearToMap
 {
+    /**
+     * Represents a segment of the line string.
+     */
     public static final class Range {
         private Range next;
 
@@ -23,9 +31,23 @@
 
         private Interpolator interpolator;
 
+        /**
+         * Default constructor.
+         */
         public Range() {
         }
 
+        /**
+         * Constructor to create a segment that maps
+         * a coordinate pair to two scalar values.
+         * Interpolations inside this segment are done with
+         * a given interpolator.
+         * @param from Start point of the segment.
+         * @param to End point of the segment.
+         * @param interpolator The interpolator.
+         * @param p1 The scalar value mapped to the start point.
+         * @param p2 The scalar value mappend to the end point.
+         */
         public Range(
             double       from,
             double       to,
@@ -44,29 +66,70 @@
                 : 1.0d/(to - from);
         }
 
+        /**
+         * Interpolated a coordinate on the segment given a scalar value
+         * between the start and end point of the range.
+         * @param x The scalar value.
+         * @param v The interpolated value is stored here.
+         */
         public void eval(double x, Coordinate v) {
             interpolator.interpolate((x - from)*b, v);
         }
 
+        /**
+         * Checks if a given value is inside this segment.
+         * @param x The value to test
+         * @return true if inside, else false.
+         */
         public boolean inside(double x) {
             return x >= from && x <= to;
         }
 
+        /**
+         * Returns the start point of this segment.
+         * @return The start point.
+         */
         public Coordinate startPoint() {
             return p1;
         }
 
+        /**
+         * Return the end point of this segment.
+         * @return The end point.
+         */
         public Coordinate endPoint() {
             return p2;
         }
     } // class Range
 
+    /**
+     * The head of the internal range list.
+     */
     protected Range head;
+
+    /**
+     * The last accessed segment. Used to accelerate
+     * the access of the right segment.
+     */
     protected Range last;
 
+    /**
+     * Default constructor.
+     */
     public LinearToMap() {
     }
 
+    /**
+     * Constructor to create a LinearToMap that maps
+     * given scalar values to coordinates of a given
+     * list of line segments.
+     * @param path The list of line segments.
+     * @param from The start value mapped to the start point
+     * of the first line segment.
+     * @param to The end value mapped to the end point of
+     * the last line segment.
+     * @param metrics The metric used to span the 2D space.
+     */
     public LinearToMap(
         List<? extends Coordinate> path,
         double                     from,
@@ -108,6 +171,11 @@
         }
     }
 
+    /**
+     * Returns a segment on which a given value is found.
+     * @param diagramX The value.
+     * @return The segment or null if no matching segment was found.
+     */
     protected Range locateRange(double diagramX) {
 
         if (last != null && last.inside(diagramX)) {
@@ -125,6 +193,13 @@
         return null;
     }
 
+    /**
+     * Interpolates a coordinate at a given scalar position.
+     * @param diagramX The scalar position.
+     * @param v The interpolated coordinate is stored here.
+     * @return true if the scalar position is inside the
+     * spanned range of the line string, else false.
+     */
     public boolean locate(double diagramX, Coordinate v) {
         Range range = locateRange(diagramX);
         if (range == null) {
@@ -134,6 +209,13 @@
         return true;
     }
 
+    /**
+     * Returns the length of a given line string using
+     * a given metric.
+     * @param path The line string.
+     * @param metrics The used metric.
+     * @return The length of the line string.
+     */
     public static double length(
         List<? extends Coordinate> path,
         Metrics                    metrics
@@ -147,6 +229,10 @@
         return sum;
     }
 
+    /**
+     * Return the number of segments in this map.
+     * @return the number of segments.
+     */
     public int numRanges() {
         int count = 0;
         Range current = head;
@@ -157,6 +243,10 @@
         return count;
     }
 
+    /**
+     * Returns an iterator over all segments of this map.
+     * @return The iterator.
+     */
     public Iterator ranges() {
         return new Iterator() {