Javadoc improvements

vtm/src/org/oscim/core/GeometryBuffer.java

@@ -338,6 +338,13 @@ public class GeometryBuffer {
             index[indexCurrentPos + 1] = -1;
     }
 
+    /**
+     * Translate.
+     *
+     * @param dx the x translation.
+     * @param dy the y translation.
+     * @return a reference to this object.
+     */
     public GeometryBuffer translate(float dx, float dy) {
         for (int i = 0; i < pointNextPos; i += 2) {
             points[i] += dx;
@@ -346,6 +353,13 @@ public class GeometryBuffer {
         return this;
     }
 
+    /**
+     * Scale.
+     *
+     * @param scaleX the x scale.
+     * @param scaleY the y scale.
+     * @return a reference to this object.
+     */
     public GeometryBuffer scale(float scaleX, float scaleY) {
         for (int i = 0; i < pointNextPos; i += 2) {
             points[i] *= scaleX;
@@ -412,10 +426,20 @@ public class GeometryBuffer {
             throw new IllegalArgumentException("not cleared " + m + "<>" + type);
     }
 
+    /**
+     * Add a {@link Point}.
+     *
+     * @param p the point.
+     */
     public void addPoint(Point p) {
         addPoint((float) p.x, (float) p.y);
     }
 
+    /**
+     * Add a {@link PointF}.
+     *
+     * @param p the point.
+     */
     public void addPoint(PointF p) {
         addPoint(p.x, p.y);
     }

vtm/src/org/oscim/core/MapElement.java

@@ -22,19 +22,18 @@ package org.oscim.core;
 import org.oscim.theme.IRenderTheme;
 
 /**
- * The MapElement class is a reusable container for a geometry
+ * The MapElement class is a reusable container for a geometry with tags.
- * with tags.
+ * <p>
- * MapElement is created by TileDataSource(s) and passed to
+ * MapElement is created by TileDataSource(s) and passed to MapTileLoader via ITileDataSink.process().
- * MapTileLoader via ITileDataSink.process().
  * This is just a buffer that belongs to TileDataSource,
- * so don't keep a reference to it when passed as parameter.
+ * so don't keep a reference to it when passed as parameter or make sure to use a copy.
  */
 public class MapElement extends GeometryBuffer {
 
     public PointF labelPosition;
 
     /**
-     * layer of the element (0-10) overrides the theme drawing order
+     * layer of the element (0-10) overrides the theme drawing order.
      */
     public int layer;
 
@@ -84,12 +83,18 @@ public class MapElement extends GeometryBuffer {
         return null;
     }
 
+    /**
+     * @return true if this is a building, else false.
+     */
     public boolean isBuilding() { // TODO from themes (with overzoom ref)
         return tags.containsKey(Tag.KEY_BUILDING)
                 || "building".equals(tags.getValue("kind")) // Mapzen
                 || "building".equals(tags.getValue("layer")); // OpenMapTiles
     }
 
+    /**
+     * @return true if this is a building part, else false.
+     */
     public boolean isBuildingPart() { // TODO from themes (with overzoom ref)
         return tags.containsKey(Tag.KEY_BUILDING_PART)
                 || "building_part".equals(tags.getValue("kind")) // Mapzen
@@ -100,6 +105,9 @@ public class MapElement extends GeometryBuffer {
         labelPosition = new PointF(x, y);
     }
 
+    /**
+     * Set the layer of the element (0-10) to override theme drawing order.
+     */
     public void setLayer(int layer) {
         this.layer = layer;
     }

vtm/src/org/oscim/core/MercatorProjection.java

@@ -589,10 +589,22 @@ public final class MercatorProjection {
         return (long) (zoomLevelToScale(zoomLevel) - tileY - 1);
     }
 
+    /**
+     * Converts y map position to latitude in degrees.
+     *
+     * @param y the map position {@link MapPosition#getY() y}.
+     * @return the latitude in degrees.
+     */
     public static double toLatitude(double y) {
         return 90 - 360 * Math.atan(Math.exp((y - 0.5) * (2 * Math.PI))) / Math.PI;
     }
 
+    /**
+     * Converts x map position to longitude in degrees.
+     *
+     * @param x the map position {@link MapPosition#getX() x}.
+     * @return the longitude in degrees.
+     */
     public static double toLongitude(double x) {
         return 360.0 * (x - 0.5);
     }

vtm/src/org/oscim/layers/tile/TileDistanceSort.java

@@ -28,6 +28,13 @@ public class TileDistanceSort extends TimSort<MapTile> {
         super();
     }
 
+    /**
+     * Sort tiles by current {@link MapTile#distance} from map center.
+     *
+     * @param a  the tiles to be sorted.
+     * @param lo the start index.
+     * @param hi the end index (excluded).
+     */
     public static void sort(MapTile[] a, int lo, int hi) {
         int nRemaining = hi - lo;
         if (nRemaining < 2) {

vtm/src/org/oscim/map/Viewport.java

@@ -38,7 +38,13 @@ public class Viewport {
     public static final int MIN_ZOOM_LEVEL = 2;
     public static final float MIN_TILT = 0;
 
-    /* Note: limited by numTiles in TileManager to ~80° */
+    /**
+     * Limited by:
+     * <p>
+     * - numTiles in {@link org.oscim.layers.tile.TileManager#init() TileManager}
+     * <p>
+     * - tilt of map when cutting map on near and far plane.
+     */
     public static final float MAX_TILT = 65;
 
     protected double mMaxScale = (1 << MAX_ZOOM_LEVEL);
@@ -201,18 +207,25 @@ public class Viewport {
      * Get the inverse projection of the viewport, i.e. the
      * coordinates with z==0 that will be projected exactly
      * to screen corners by current view-projection-matrix.
+     * <p>
+     * Except when screen corners don't hit the map (e.g. on large tilt),
+     * then it will return the intersection with near and far plane.
      *
-     * @param box float[8] will be set.
+     * @param box float[8] will be set to
+     *            0,1 -> x,y bottom-right,
+     *            2,3 -> x,y bottom-left,
+     *            4,5 -> x,y top-left,
+     *            6,7 -> x,y top-right.
      * @param add increase extents of box
      */
     public void getMapExtents(float[] box, float add) {
-        /* top-right */
-        unproject(1, -1, box, 0);
-        /* top-left */
-        unproject(-1, -1, box, 2);
-        /* bottom-left */
-        unproject(-1, 1, box, 4);
         /* bottom-right */
+        unproject(1, -1, box, 0);
+        /* bottom-left */
+        unproject(-1, -1, box, 2);
+        /* top-left */
+        unproject(-1, 1, box, 4);
+        /* top-right */
         unproject(1, 1, box, 6);
 
         if (add == 0)
@@ -315,7 +328,7 @@ public class Viewport {
     }
 
     /**
-     * Get the GeoPoint for x,y in screen coordinates.
+     * Get the GeoPoint for x,y from screen coordinates.
      *
      * @param x screen coordinate
      * @param y screen coordinate
@@ -337,10 +350,11 @@ public class Viewport {
     }
 
     /**
-     * Get the map position for x,y in screen coordinates.
+     * Get the map position x,y from screen coordinates.
      *
-     * @param x screen coordinate
+     * @param x   screen coordinate
-     * @param y screen coordinate
+     * @param y   screen coordinate
+     * @param out map position as Point {@link MapPosition#getX() x} and {@link MapPosition#getY() y}
      */
     public synchronized void fromScreenPoint(double x, double y, Point out) {
         unprojectScreen(x, y, mu);

vtm/src/org/oscim/utils/ScanBox.java

@@ -88,8 +88,20 @@ public abstract class ScanBox {
 
     protected int mZoom;
 
+    /**
+     * @param y  the y-number of tile to be set visible.
+     * @param x1 the start x-number of tile to be set visible.
+     * @param x2 the end x-number of tile to be set visible (excluded).
+     */
     protected abstract void setVisible(int y, int x1, int x2);
 
+    /**
+     * @param x     Projected map position x in 0..1.
+     * @param y     Projected map position y in 0..1.
+     * @param scale Absolute scale.
+     * @param zoom  Tile zoom level for current scale.
+     * @param box   Current visible cut-out (8 floats).
+     */
     public void scan(double x, double y, double scale, int zoom, float[] box) {
         mZoom = zoom;
         // this does not modify 'box' parameter
@@ -116,20 +128,20 @@ public abstract class ScanBox {
         xmin = (int) min;
         xmax = (int) max;
 
-        // top-right -> top-left
+        // bottom-right -> bottom-left
         ab.set(box[0], box[1], box[2], box[3]);
-        // top-left ->  bottom-left
+        // bottom-left -> top-left
         bc.set(box[2], box[3], box[4], box[5]);
-        // bottom-left -> top-right
+        // top-left -> bottom-right
         ca.set(box[4], box[5], box[0], box[1]);
 
         scanTriangle();
 
-        // top-right -> bottom-left
+        // bottom-right -> top-left
         ab.set(box[0], box[1], box[4], box[5]);
-        // bottom-left -> bottom-right
+        // top-left -> top-right
         bc.set(box[4], box[5], box[6], box[7]);
-        // bottom-right -> top-right
+        // top-right -> bottom-right
         ca.set(box[6], box[7], box[0], box[1]);
 
         scanTriangle();