LUCENE-6675: spatial3d passes method level javadocs linting

git-svn-id: https://svn.apache.org/repos/asf/lucene/dev/trunk@1690833 13f79535-47bb-0310-9956-ffa450edef68

lucene/build.xml

@@ -189,8 +189,7 @@
     <check-missing-javadocs dir="build/docs/core/org/apache/lucene/index" level="method"/>
     <check-missing-javadocs dir="build/docs/core/org/apache/lucene/codecs" level="method"/>
 
-    <!-- spatial3d: problems -->
-    <!-- <check-missing-javadocs dir="build/docs/spatial3d" level="method"/>--> 
+    <check-missing-javadocs dir="build/docs/spatial3d" level="method"/>
   </target>
   
   <target name="-ecj-javadoc-lint" depends="compile,compile-test,-ecj-javadoc-lint-unsupported,-ecj-resolve" if="ecj-javadoc-lint.supported">

lucene/spatial3d/src/java/org/apache/lucene/geo3d/ArcDistance.java

@@ -27,6 +27,11 @@ public class ArcDistance implements DistanceStyle {
   /** An instance of the ArcDistance DistanceStyle. */
   public final static ArcDistance INSTANCE = new ArcDistance();
   
+  /** Constructor.
+   */
+  public ArcDistance() {
+  }
+  
   @Override
   public double computeDistance(final GeoPoint point1, final GeoPoint point2) {
     return point1.arcDistance(point2);

lucene/spatial3d/src/java/org/apache/lucene/geo3d/GeoPath.java

@@ -592,6 +592,13 @@ public class GeoPath extends GeoBaseDistanceShape {
     /** Notable points for the end cutoff plane */
     public final GeoPoint[] endCutoffPlanePoints;
 
+    /** Construct a path segment.
+     *@param planetModel is the planet model.
+     *@param start is the starting point.
+     *@param end is the ending point.
+     *@param normalizedConnectingPlane is the connecting plane.
+     *@param planeBoundingOffset is the linear offset from the connecting plane to either side.
+     */
     public PathSegment(final PlanetModel planetModel, final GeoPoint start, final GeoPoint end,
       final Plane normalizedConnectingPlane, final double planeBoundingOffset) {
       this.start = start;

lucene/spatial3d/src/java/org/apache/lucene/geo3d/GeoWideDegenerateHorizontalLine.java

@@ -23,28 +23,44 @@ package org.apache.lucene.geo3d;
  * @lucene.internal
  */
 public class GeoWideDegenerateHorizontalLine extends GeoBaseBBox {
+  /** The latitude of the line */
   protected final double latitude;
+  /** The left longitude cutoff of the line */
   protected final double leftLon;
+  /** The right longitude cutoff of the line */
   protected final double rightLon;
 
+  /** The left end of the line */
   protected final GeoPoint LHC;
+  /** The right end of the line */
   protected final GeoPoint RHC;
 
+  /** The plane the line is in */
   protected final Plane plane;
+  /** The left cutoff plane */
   protected final SidedPlane leftPlane;
+  /** The right cutoff plane */
   protected final SidedPlane rightPlane;
 
+  /** Notable points for the line */
   protected final GeoPoint[] planePoints;
 
+  /** Center point for the line */
   protected final GeoPoint centerPoint;
 
+  /** Left/right combination bound */
   protected final EitherBound eitherBound;
 
+  /** A point on the line */
   protected final GeoPoint[] edgePoints;
 
   /**
    * Accepts only values in the following ranges: lat: {@code -PI/2 -> PI/2}, lon: {@code -PI -> PI}.
    * Horizontal angle must be greater than or equal to PI.
+   *@param planetModel is the planet model.
+   *@param latitude is the line latitude.
+   *@param leftLon is the left cutoff longitude.
+   *@param rightLon is the right cutoff longitude.
    */
   public GeoWideDegenerateHorizontalLine(final PlanetModel planetModel, final double latitude, final double leftLon, double rightLon) {
     super(planetModel);
@@ -205,7 +221,11 @@ public class GeoWideDegenerateHorizontalLine extends GeoBaseBBox {
     return "GeoWideDegenerateHorizontalLine: {planetmodel="+planetModel+", latitude=" + latitude + "(" + latitude * 180.0 / Math.PI + "), leftlon=" + leftLon + "(" + leftLon * 180.0 / Math.PI + "), rightLon=" + rightLon + "(" + rightLon * 180.0 / Math.PI + ")}";
   }
 
+  /** Membership implementation representing a wide cutoff (more than 180 degrees).
+   */
   protected class EitherBound implements Membership {
+    /** Constructor.
+     */
     public EitherBound() {
     }
 

lucene/spatial3d/src/java/org/apache/lucene/geo3d/GeoWideLongitudeSlice.java

@@ -24,21 +24,31 @@ package org.apache.lucene.geo3d;
  * @lucene.internal
  */
 public class GeoWideLongitudeSlice extends GeoBaseBBox {
+  /** The left longitude */
   protected final double leftLon;
+  /** The right longitude */
   protected final double rightLon;
 
+  /** The left plane */
   protected final SidedPlane leftPlane;
+  /** The right plane */
   protected final SidedPlane rightPlane;
 
+  /** Notable points for the shape */
   protected final GeoPoint[] planePoints;
 
+  /** Center point for the shape */
   protected final GeoPoint centerPoint;
 
+  /** A point on the edge of the shape */
   protected final GeoPoint[] edgePoints; 
 
   /**
    * Accepts only values in the following ranges: lon: {@code -PI -> PI}.
    * Horizantal angle must be greater than or equal to PI.
+   *@param planetModel is the planet model.
+   *@param leftLon is the left longitude.
+   *@param rightLon is the right longitude.
    */
   public GeoWideLongitudeSlice(final PlanetModel planetModel, final double leftLon, double rightLon) {
     super(planetModel);

lucene/spatial3d/src/java/org/apache/lucene/geo3d/GeoWideNorthRectangle.java

@@ -24,27 +24,42 @@ package org.apache.lucene.geo3d;
  * @lucene.internal
  */
 public class GeoWideNorthRectangle extends GeoBaseBBox {
+  /** Bottom latitude */
   protected final double bottomLat;
+  /** Left longitude */
   protected final double leftLon;
+  /** Right longitude */
   protected final double rightLon;
 
+  /** The cosine of the middle latitude */
   protected final double cosMiddleLat;
 
+  /** The lower right hand corner point */
   protected final GeoPoint LRHC;
+  /** The lower left hand corner point */
   protected final GeoPoint LLHC;
 
+  /** The bottom plane */
   protected final SidedPlane bottomPlane;
+  /** The left plane */
   protected final SidedPlane leftPlane;
+  /** The right plane */
   protected final SidedPlane rightPlane;
 
+  /** Notable points for the bottom plane */
   protected final GeoPoint[] bottomPlanePoints;
+  /** Notable points for the left plane */
   protected final GeoPoint[] leftPlanePoints;
+  /** Notable points for the right plane */
   protected final GeoPoint[] rightPlanePoints;
 
+  /** Center point */
   protected final GeoPoint centerPoint;
 
+  /** Composite left/right bounds */
   protected final EitherBound eitherBound;
 
+  /** A point on the edge */
   protected final GeoPoint[] edgePoints;
 
   /**
@@ -248,7 +263,11 @@ public class GeoWideNorthRectangle extends GeoBaseBBox {
     return "GeoWideNorthRectangle: {planetmodel="+planetModel+", bottomlat=" + bottomLat + "(" + bottomLat * 180.0 / Math.PI + "), leftlon=" + leftLon + "(" + leftLon * 180.0 / Math.PI + "), rightlon=" + rightLon + "(" + rightLon * 180.0 / Math.PI + ")}";
   }
 
+  /** Membership implementation representing a wide (more than 180 degree) bound.
+   */
   protected class EitherBound implements Membership {
+    /** Constructor.
+     */
     public EitherBound() {
     }
 

lucene/spatial3d/src/java/org/apache/lucene/geo3d/GeoWideRectangle.java

@@ -24,32 +24,52 @@ package org.apache.lucene.geo3d;
  * @lucene.internal
  */
 public class GeoWideRectangle extends GeoBaseBBox {
+  /** The top latitude */
   protected final double topLat;
+  /** The bottom latitude */
   protected final double bottomLat;
+  /** The left longitude */
   protected final double leftLon;
+  /** The right longitude */
   protected final double rightLon;
 
+  /** Cosine of the middle latitude */
   protected final double cosMiddleLat;
 
+  /** Upper left hand corner point */
   protected final GeoPoint ULHC;
+  /** Lower right hand corner point */
   protected final GeoPoint URHC;
+  /** Lower right hand corner point */
   protected final GeoPoint LRHC;
+  /** Lower left hand corner point */
   protected final GeoPoint LLHC;
 
+  /** Top plane */
   protected final SidedPlane topPlane;
+  /** Bottom plane */
   protected final SidedPlane bottomPlane;
+  /** Left plane */
   protected final SidedPlane leftPlane;
+  /** Right plane */
   protected final SidedPlane rightPlane;
 
+  /** Top plane's notable points */
   protected final GeoPoint[] topPlanePoints;
+  /** Bottom plane's notable points */
   protected final GeoPoint[] bottomPlanePoints;
+  /** Left plane's notable points */
   protected final GeoPoint[] leftPlanePoints;
+  /** Right plane's notable points */
   protected final GeoPoint[] rightPlanePoints;
 
+  /** Center point */
   protected final GeoPoint centerPoint;
 
+  /** Combined left/right bounds */
   protected final EitherBound eitherBound;
 
+  /** A point on the edge */
   protected final GeoPoint[] edgePoints;
 
   /**
@@ -276,7 +296,11 @@ public class GeoWideRectangle extends GeoBaseBBox {
     return "GeoWideRectangle: {planetmodel=" + planetModel + ", toplat=" + topLat + "(" + topLat * 180.0 / Math.PI + "), bottomlat=" + bottomLat + "(" + bottomLat * 180.0 / Math.PI + "), leftlon=" + leftLon + "(" + leftLon * 180.0 / Math.PI + "), rightlon=" + rightLon + "(" + rightLon * 180.0 / Math.PI + ")}";
   }
 
+  /** A membership implementation representing a wide (more than 180) left/right bound.
+   */
   protected class EitherBound implements Membership {
+    /** Constructor.
+      */
     public EitherBound() {
     }
 

lucene/spatial3d/src/java/org/apache/lucene/geo3d/GeoWideSouthRectangle.java

@@ -24,27 +24,42 @@ package org.apache.lucene.geo3d;
  * @lucene.internal
  */
 public class GeoWideSouthRectangle extends GeoBaseBBox {
+  /** Top latitude of rect */
   protected final double topLat;
+  /** Left longitude of rect */
   protected final double leftLon;
+  /** Right longitude of rect */
   protected final double rightLon;
 
+  /** Cosine of middle latitude */
   protected final double cosMiddleLat;
 
+  /** Upper left hand corner */
   protected final GeoPoint ULHC;
+  /** Upper right hand corner */
   protected final GeoPoint URHC;
 
+  /** The top plane */
   protected final SidedPlane topPlane;
+  /** The left plane */
   protected final SidedPlane leftPlane;
+  /** The right plane */
   protected final SidedPlane rightPlane;
 
+  /** Notable points for top plane */
   protected final GeoPoint[] topPlanePoints;
+  /** Notable points for left plane */
   protected final GeoPoint[] leftPlanePoints;
+  /** Notable points for right plane */
   protected final GeoPoint[] rightPlanePoints;
 
+  /** Center point */
   protected final GeoPoint centerPoint;
 
+  /** Left/right bounds */
   protected final EitherBound eitherBound;
 
+  /** A point on the edge */
   protected final GeoPoint[] edgePoints;
 
   /**
@@ -246,7 +261,11 @@ public class GeoWideSouthRectangle extends GeoBaseBBox {
     return "GeoWideSouthRectangle: {planetmodel="+planetModel+", toplat=" + topLat + "(" + topLat * 180.0 / Math.PI + "), leftlon=" + leftLon + "(" + leftLon * 180.0 / Math.PI + "), rightlon=" + rightLon + "(" + rightLon * 180.0 / Math.PI + ")}";
   }
 
+  /** Membership implementation representing width more than 180.
+   */
   protected class EitherBound implements Membership {
+    /** Constructor.
+     */
     public EitherBound() {
     }
 

lucene/spatial3d/src/java/org/apache/lucene/geo3d/GeoWorld.java

@@ -23,9 +23,14 @@ package org.apache.lucene.geo3d;
  * @lucene.internal
  */
 public class GeoWorld extends GeoBaseBBox {
+  /** No points on the edge of the shape */
   protected final static GeoPoint[] edgePoints = new GeoPoint[0];
+  /** Point in the middle of the world */
   protected final GeoPoint originPoint;
   
+  /** Constructor.
+   *@param planetModel is the planet model.
+   */
   public GeoWorld(final PlanetModel planetModel) {
     super(planetModel);
     originPoint = new GeoPoint(planetModel.ab, 1.0, 0.0, 0.0);

lucene/spatial3d/src/java/org/apache/lucene/geo3d/LinearDistance.java

@@ -24,8 +24,14 @@ package org.apache.lucene.geo3d;
  */
 public class LinearDistance implements DistanceStyle {
   
+  /** A convenient instance */
   public final static LinearDistance INSTANCE = new LinearDistance();
   
+  /** Constructor.
+   */
+  public LinearDistance() {
+  }
+  
   @Override
   public double computeDistance(final GeoPoint point1, final GeoPoint point2) {
     return point1.linearDistance(point2);

lucene/spatial3d/src/java/org/apache/lucene/geo3d/LinearSquaredDistance.java

@@ -24,8 +24,14 @@ package org.apache.lucene.geo3d;
  */
 public class LinearSquaredDistance implements DistanceStyle {
   
+  /** A convenient instance */
   public final static LinearSquaredDistance INSTANCE = new LinearSquaredDistance();
   
+  /** Constructor.
+   */
+  public LinearSquaredDistance() {
+  }
+  
   @Override
   public double computeDistance(final GeoPoint point1, final GeoPoint point2) {
     return point1.linearDistanceSquared(point2);

lucene/spatial3d/src/java/org/apache/lucene/geo3d/NormalDistance.java

@@ -24,8 +24,14 @@ package org.apache.lucene.geo3d;
  */
 public class NormalDistance implements DistanceStyle {
   
+  /** A convenient instance */
   public final static NormalDistance INSTANCE = new NormalDistance();
   
+  /** Constructor.
+   */
+  public NormalDistance() {
+  }
+  
   @Override
   public double computeDistance(final GeoPoint point1, final GeoPoint point2) {
     return point1.normalDistance(point2);

lucene/spatial3d/src/java/org/apache/lucene/geo3d/NormalSquaredDistance.java

@@ -24,8 +24,14 @@ package org.apache.lucene.geo3d;
  */
 public class NormalSquaredDistance implements DistanceStyle {
   
+  /** A convenient instance */
   public final static NormalSquaredDistance INSTANCE = new NormalSquaredDistance();
   
+  /** Constructor.
+   */
+  public NormalSquaredDistance() {
+  }
+  
   @Override
   public double computeDistance(final GeoPoint point1, final GeoPoint point2) {
     return point1.normalDistanceSquared(point2);

lucene/spatial3d/src/java/org/apache/lucene/geo3d/Plane.java

@@ -24,13 +24,19 @@ package org.apache.lucene.geo3d;
  * @lucene.experimental
  */
 public class Plane extends Vector {
+  /** An array with no points in it */
   protected final static GeoPoint[] NO_POINTS = new GeoPoint[0];
+  /** An array with no bounds in it */
   protected final static Membership[] NO_BOUNDS = new Membership[0];
-
+  /** Ax + By + Cz + D = 0 */
   public final double D;
 
   /**
    * Construct a plane with all four coefficients defined.
+   *@param A is A
+   *@param B is B
+   *@param C is C
+   *@param D is D
    */
   public Plane(final double A, final double B, final double C, final double D) {
     super(A, B, C);
@@ -74,7 +80,7 @@ public class Plane extends Vector {
   /**
    * Construct a plane with a specific vector, and D offset
    * from origin.
-   *
+   * @param v is the normal vector.
    * @param D is the D offset from the origin.
    */
   public Plane(final Vector v, final double D) {
@@ -83,8 +89,10 @@ public class Plane extends Vector {
   }
 
   /** Construct the most accurate normalized, vertical plane given a set of points.  If none of the points can determine
-  * the plane, return null.
-  */
+   * the plane, return null.
+   * @param planePoints is a set of points to choose from.  The best one for constructing the most precise normal plane is picked.
+   * @return the normal plane
+   */
   public static Plane constructNormalizedVerticalPlane(final Vector... planePoints) {
     // Pick the best one (with the greatest x-y distance)
     double bestDistance = 0.0;
@@ -100,7 +108,10 @@ public class Plane extends Vector {
   }
 
   /** Construct a normalized, vertical plane through an x-y point.  If the x-y point is at (0,0), return null.
-  */
+   * @param x is the x value.
+   * @param y is the y value.
+   * @return a vertical plane passing through the center and (x,y,0).
+   */
   public static Plane constructNormalizedVerticalPlane(final double x, final double y) {
     if (Math.abs(x) < MINIMUM_RESOLUTION && Math.abs(y) < MINIMUM_RESOLUTION)
       return null;
@@ -122,6 +133,10 @@ public class Plane extends Vector {
   /**
    * Evaluate the plane equation for a given point, as represented
    * by a vector.
+   * @param x is the x value.
+   * @param y is the y value.
+   * @param z is the z value.
+   * @return the result of the evaluation.
    */
   public double evaluate(final double x, final double y, final double z) {
     return dotProduct(x, y, z) + D;
@@ -142,6 +157,9 @@ public class Plane extends Vector {
    * Evaluate the plane equation for a given point, as represented
    * by a vector.
    *
+   * @param x is the x value.
+   * @param y is the y value.
+   * @param z is the z value.
    * @return true if the result is on the plane.
    */
   public boolean evaluateIsZero(final double x, final double y, final double z) {
@@ -160,16 +178,19 @@ public class Plane extends Vector {
     return new Plane(normVect, this.D);
   }
 
-  /** @see #arcDistance(PlanetModel, double, double, double, Membership...) */
+  /** Compute arc distance from plane to a vector expressed with a {@link GeoPoint}.
+   *  @see #arcDistance(PlanetModel, double, double, double, Membership...) */
   public double arcDistance(final PlanetModel planetModel, final GeoPoint v, final Membership... bounds) {
     return arcDistance(planetModel, v.x, v.y, v.z, bounds);
   }
     
   /**
    * Compute arc distance from plane to a vector.
+   * @param planetModel is the planet model.
    * @param x is the x vector value.
    * @param y is the y vector value.
    * @param z is the z vector value.
+   * @param bounds are the bounds which constrain the intersection point.
    * @return the arc distance.
    */
   public double arcDistance(final PlanetModel planetModel, final double x, final double y, final double z, final Membership... bounds) {
@@ -207,6 +228,7 @@ public class Plane extends Vector {
   /**
    * Compute normal distance from plane to a vector.
    * @param v is the vector.
+   * @param bounds are the bounds which constrain the intersection point.
    * @return the normal distance.
    */
   public double normalDistance(final Vector v, final Membership... bounds) {
@@ -218,6 +240,7 @@ public class Plane extends Vector {
    * @param x is the vector x.
    * @param y is the vector y.
    * @param z is the vector z.
+   * @param bounds are the bounds which constrain the intersection point.
    * @return the normal distance.
    */
   public double normalDistance(final double x, final double y, final double z, final Membership... bounds) {
@@ -237,6 +260,7 @@ public class Plane extends Vector {
   /**
    * Compute normal distance squared from plane to a vector.
    * @param v is the vector.
+   * @param bounds are the bounds which constrain the intersection point.
    * @return the normal distance squared.
    */
   public double normalDistanceSquared(final Vector v, final Membership... bounds) {
@@ -248,6 +272,7 @@ public class Plane extends Vector {
    * @param x is the vector x.
    * @param y is the vector y.
    * @param z is the vector z.
+   * @param bounds are the bounds which constrain the intersection point.
    * @return the normal distance squared.
    */
   public double normalDistanceSquared(final double x, final double y, final double z, final Membership... bounds) {
@@ -261,7 +286,9 @@ public class Plane extends Vector {
    * Compute linear distance from plane to a vector.  This is defined
    * as the distance from the given point to the nearest intersection of 
    * this plane with the planet surface.
-   * @param v is the vector.
+   * @param planetModel is the planet model.
+   * @param v is the point.
+   * @param bounds are the bounds which constrain the intersection point.
    * @return the linear distance.
    */
   public double linearDistance(final PlanetModel planetModel, final GeoPoint v, final Membership... bounds) {
@@ -272,9 +299,11 @@ public class Plane extends Vector {
    * Compute linear distance from plane to a vector.  This is defined
    * as the distance from the given point to the nearest intersection of 
    * this plane with the planet surface.
+   * @param planetModel is the planet model.
    * @param x is the vector x.
    * @param y is the vector y.
    * @param z is the vector z.
+   * @param bounds are the bounds which constrain the intersection point.
    * @return the linear distance.
    */
   public double linearDistance(final PlanetModel planetModel, final double x, final double y, final double z, final Membership... bounds) {
@@ -311,7 +340,9 @@ public class Plane extends Vector {
    * Compute linear distance squared from plane to a vector.  This is defined
    * as the distance from the given point to the nearest intersection of 
    * this plane with the planet surface.
-   * @param v is the vector.
+   * @param planetModel is the planet model.
+   * @param v is the point.
+   * @param bounds are the bounds which constrain the intersection point.
    * @return the linear distance squared.
    */
   public double linearDistanceSquared(final PlanetModel planetModel, final GeoPoint v, final Membership... bounds) {
@@ -322,9 +353,11 @@ public class Plane extends Vector {
    * Compute linear distance squared from plane to a vector.  This is defined
    * as the distance from the given point to the nearest intersection of 
    * this plane with the planet surface.
+   * @param planetModel is the planet model.
    * @param x is the vector x.
    * @param y is the vector y.
    * @param z is the vector z.
+   * @param bounds are the bounds which constrain the intersection point.
    * @return the linear distance squared.
    */
   public double linearDistanceSquared(final PlanetModel planetModel, final double x, final double y, final double z, final Membership... bounds) {
@@ -336,6 +369,10 @@ public class Plane extends Vector {
    * Find points on the boundary of the intersection of a plane and the unit sphere,
    * given a starting point, and ending point, and a list of proportions of the arc (e.g. 0.25, 0.5, 0.75).
    * The angle between the starting point and ending point is assumed to be less than pi.
+   * @param start is the start point.
+   * @param end is the end point.
+   * @param proportions is an array of fractional proportions measured between start and end.
+   * @return an array of points corresponding to the proportions passed in.
    */
   public GeoPoint[] interpolate(final GeoPoint start, final GeoPoint end, final double[] proportions) {
     // Steps:
@@ -473,6 +510,15 @@ public class Plane extends Vector {
 
   /**
    * Modify a point to produce a vector in translated/rotated space.
+   * @param start is the start point.
+   * @param transX is the translation x value.
+   * @param transY is the translation y value.
+   * @param transZ is the translation z value.
+   * @param sinRA is the sine of the ascension angle.
+   * @param cosRA is the cosine of the ascension angle.
+   * @param sinHA is the sine of the height angle.
+   * @param cosHA is the cosine of the height angle.
+   * @return the modified point.
    */
   protected static Vector modify(final GeoPoint start, final double transX, final double transY, final double transZ,
                                  final double sinRA, final double cosRA, final double sinHA, final double cosHA) {
@@ -481,6 +527,15 @@ public class Plane extends Vector {
 
   /**
    * Reverse modify a point to produce a GeoPoint in normal space.
+   * @param point is the translated point.
+   * @param transX is the translation x value.
+   * @param transY is the translation y value.
+   * @param transZ is the translation z value.
+   * @param sinRA is the sine of the ascension angle.
+   * @param cosRA is the cosine of the ascension angle.
+   * @param sinHA is the sine of the height angle.
+   * @param cosHA is the cosine of the height angle.
+   * @return the original point.
    */
   protected static GeoPoint reverseModify(final Vector point, final double transX, final double transY, final double transZ,
                                           final double sinRA, final double cosRA, final double sinHA, final double cosHA) {
@@ -490,6 +545,10 @@ public class Plane extends Vector {
 
   /**
    * Public version of findIntersections.
+   * @param planetModel is the planet model.
+   * @param q is the plane to intersect with.
+   * @param bounds are the bounds to consider to determine legal intersection points.
+   * @return the set of legal intersection points.
    */
   public GeoPoint[] findIntersections(final PlanetModel planetModel, final Plane q, final Membership... bounds) {
     if (isNumericallyIdentical(q)) {
@@ -967,6 +1026,13 @@ public class Plane extends Vector {
 
   }
 
+  /** Add a point to boundsInfo if within a specifically bounded area.
+   * @param boundsInfo is the object to be modified.
+   * @param bounds is the area that the point must be within.
+   * @param x is the x value.
+   * @param y is the y value.
+   * @param z is the z value.
+   */
   protected static void addPoint(final Bounds boundsInfo, final Membership[] bounds, final double x, final double y, final double z) {
     //System.err.println(" Want to add point x="+x+" y="+y+" z="+z);
     // Make sure the discovered point is within the bounds
@@ -1022,6 +1088,8 @@ public class Plane extends Vector {
 
   /**
    * Returns true if this plane and the other plane are identical within the margin of error.
+   * @param p is the plane to compare against.
+   * @return true if the planes are numerically identical.
    */
   protected boolean isNumericallyIdentical(final Plane p) {
     // We can get the correlation by just doing a parallel plane check.  If that passes, then compute a point on the plane
@@ -1050,10 +1118,24 @@ public class Plane extends Vector {
     return evaluateIsZero(-p.x * p.D * denom, -p.y * p.D * denom, -p.z * p.D * denom);
   }
 
+  /**
+   * Check if a vector meets the provided bounds.
+   * @param p is the vector.
+   * @param bounds are the bounds.
+   * @return true if the vector describes a point within the bounds.
+   */
   protected static boolean meetsAllBounds(final Vector p, final Membership[] bounds) {
     return meetsAllBounds(p.x, p.y, p.z, bounds);
   }
 
+  /**
+   * Check if a vector meets the provided bounds.
+   * @param x is the x value.
+   * @param y is the y value.
+   * @param z is the z value.
+   * @param bounds are the bounds.
+   * @return true if the vector describes a point within the bounds.
+   */
   protected static boolean meetsAllBounds(final double x, final double y, final double z, final Membership[] bounds) {
     for (final Membership bound : bounds) {
       if (!bound.isWithin(x,y,z))
@@ -1062,17 +1144,36 @@ public class Plane extends Vector {
     return true;
   }
 
+  /**
+   * Check if a vector meets the provided bounds.
+   * @param p is the vector.
+   * @param bounds are the bounds.
+   * @param moreBounds are an additional set of bounds.
+   * @return true if the vector describes a point within the bounds.
+   */
   protected static boolean meetsAllBounds(final Vector p, final Membership[] bounds, final Membership[] moreBounds) {
     return meetsAllBounds(p.x, p.y, p.z, bounds, moreBounds);
   }
 
+  /**
+   * Check if a vector meets the provided bounds.
+   * @param x is the x value.
+   * @param y is the y value.
+   * @param z is the z value.
+   * @param bounds are the bounds.
+   * @param moreBounds are an additional set of bounds.
+   * @return true if the vector describes a point within the bounds.
+   */
   protected static boolean meetsAllBounds(final double x, final double y, final double z, final Membership[] bounds,
                                           final Membership[] moreBounds) {
     return meetsAllBounds(x,y,z, bounds) && meetsAllBounds(x,y,z, moreBounds);
   }
 
   /**
-   * Find a sample point on the intersection between two planes and the unit sphere.
+   * Find a sample point on the intersection between two planes and the world.
+   * @param planetModel is the planet model.
+   * @param q is the second plane to consider.
+   * @return a sample point that is on the intersection between the two planes and the world.
    */
   public GeoPoint getSampleIntersectionPoint(final PlanetModel planetModel, final Plane q) {
     final GeoPoint[] intersections = findIntersections(planetModel, q, NO_BOUNDS, NO_BOUNDS);

lucene/spatial3d/src/java/org/apache/lucene/geo3d/PlanetModel.java

@@ -39,20 +39,37 @@ public class PlanetModel {
   // Surface of the planet:
   // x^2/a^2 + y^2/b^2 + z^2/c^2 = 1.0
   // Scaling factors are a,b,c.  geo3d can only support models where a==b, so use ab instead.
+  
+  /** The x/y scaling factor */
   public final double ab;
+  /** The z scaling factor */
   public final double c;
+  /** The inverse of ab */
   public final double inverseAb;
+  /** The inverse of c */
   public final double inverseC;
+  /** The square of the inverse of ab */
   public final double inverseAbSquared;
+  /** The square of the inverse of c */
   public final double inverseCSquared;
+  /** The flattening value */
   public final double flattening;
+  /** The square ratio */
   public final double squareRatio;
+  
   // We do NOT include radius, because all computations in geo3d are in radians, not meters.
   
   // Compute north and south pole for planet model, since these are commonly used.
+  
+  /** North pole */
   public final GeoPoint NORTH_POLE;
+  /** South pole */
   public final GeoPoint SOUTH_POLE;
   
+  /** Constructor.
+   * @param ab is the x/y scaling factor.
+   * @param c is the z scaling factor.
+   */
   public PlanetModel(final double ab, final double c) {
     this.ab = ab;
     this.c = c;
@@ -67,12 +84,14 @@ public class PlanetModel {
   }
   
   /** Find the minimum magnitude of all points on the ellipsoid.
+   * @return the minimum magnitude for the planet.
    */
   public double getMinimumMagnitude() {
     return Math.min(this.ab, this.c);
   }
 
   /** Find the maximum magnitude of all points on the ellipsoid.
+   * @return the maximum magnitude for the planet.
    */
   public double getMaximumMagnitude() {
     return Math.max(this.ab, this.c);

lucene/spatial3d/src/java/org/apache/lucene/geo3d/SidedPlane.java

@@ -24,6 +24,7 @@ package org.apache.lucene.geo3d;
  * @lucene.experimental
  */
 public class SidedPlane extends Plane implements Membership {
+  /** The sign value for evaluation of a point on the correct side of the plane */
   public final double sigNum;
 
   /**

lucene/spatial3d/src/java/org/apache/lucene/geo3d/Vector.java

@@ -33,15 +33,23 @@ public class Vector {
    * For squared quantities, the bound is squared too.
    */
   public static final double MINIMUM_RESOLUTION_SQUARED = MINIMUM_RESOLUTION * MINIMUM_RESOLUTION;
-
+  /**
+   * For cubed quantities, cube the bound.
+   */
   public static final double MINIMUM_RESOLUTION_CUBED = MINIMUM_RESOLUTION_SQUARED * MINIMUM_RESOLUTION;
 
+  /** The x value */
   public final double x;
+  /** The y value */
   public final double y;
+  /** The z value */
   public final double z;
 
   /**
    * Construct from (U.S.) x,y,z coordinates.
+   *@param x is the x value.
+   *@param y is the y value.
+   *@param z is the z value.
    */
   public Vector(double x, double y, double z) {
     this.x = x;