Added some documentation to the spatial.query package. Some reformatting too.

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

lucene/spatial/src/java/org/apache/lucene/spatial/query/SpatialArgs.java

@@ -23,6 +23,8 @@ import com.spatial4j.core.exception.InvalidSpatialArgument;
 import com.spatial4j.core.shape.Shape;
 
 /**
+ * Principally holds the query {@link Shape} and the {@link SpatialOperation}.
+ *
  * @lucene.experimental
  */
 public class SpatialArgs {
@@ -46,9 +48,7 @@ public class SpatialArgs {
     this.shape = shape;
   }
 
-  /**
-   * Check if the arguments make sense -- throw an exception if not
-   */
+  /** Check if the arguments make sense -- throw an exception if not */
   public void validate() throws InvalidSpatialArgument {
     if (operation.isTargetNeedsArea() && !shape.hasArea()) {
       throw new InvalidSpatialArgument(operation + " only supports geometry with area");
@@ -71,8 +71,7 @@ public class SpatialArgs {
   }
 
   @Override
-  public String toString()
-  {
+  public String toString() {
     return toString(SimpleSpatialContext.GEO_KM);
   }
 
@@ -88,9 +87,7 @@ public class SpatialArgs {
     this.operation = operation;
   }
 
-  /**
-   * Considers {@link SpatialOperation#BBoxWithin} in returning the shape.
-   */
+  /** Considers {@link SpatialOperation#BBoxWithin} in returning the shape. */
   public Shape getShape() {
     if (shape != null && (operation == SpatialOperation.BBoxWithin || operation == SpatialOperation.BBoxIntersects))
       return shape.getBoundingBox();
@@ -102,9 +99,10 @@ public class SpatialArgs {
   }
 
   /**
-   * The fraction of the distance from the center of the query shape to its nearest edge that is considered acceptable
-   * error. The algorithm for computing the distance to the nearest edge is actually a little different. It normalizes
-   * the shape to a square given it's bounding box area:
+   * The fraction of the distance from the center of the query shape to its nearest edge
+   * that is considered acceptable error. The algorithm for computing the distance to the
+   * nearest edge is actually a little different. It normalizes the shape to a square
+   * given it's bounding box area:
    * <pre>sqrt(shape.bbox.area)/2</pre>
    * And the error distance is beyond the shape such that the shape is a minimum shape.
    */

lucene/spatial/src/java/org/apache/lucene/spatial/query/SpatialArgsParser.java

@@ -27,10 +27,32 @@ import java.util.Map;
 import java.util.StringTokenizer;
 
 /**
+ * Parses a string that usually looks like "OPERATION(SHAPE)" into a {@link SpatialArgs}
+ * object. The set of operations supported are defined in {@link SpatialOperation}, such
+ * as "Intersects" being a common one. The shape portion is defined by {@link
+ * SpatialContext#readShape(String)}. There are some optional name-value pair parameters
+ * that follow the closing parenthesis.  Example:
+ * <pre>
+ *   Intersects(-10,20,-8,22) distPec=0.025
+ * </pre>
+ * <p/>
+ * In the future it would be good to support something at least semi-standardized like a
+ * variant of <a href="http://docs.geoserver.org/latest/en/user/filter/ecql_reference.html#spatial-predicate">
+ *   [E]CQL</a>.
+ *
  * @lucene.experimental
  */
-public class SpatialArgsParser
-{
+public class SpatialArgsParser {
+
+  /**
+   * Parses a string such as "Intersects(-10,20,-8,22) distPec=0.025".
+   *
+   * @param v   The string to parse. Mandatory.
+   * @param ctx The spatial context. Mandatory.
+   * @return Not null.
+   * @throws InvalidSpatialArgument If there is a problem parsing the string.
+   * @throws InvalidShapeException  Thrown from {@link SpatialContext#readShape(String)}
+   */
   public SpatialArgs parse(String v, SpatialContext ctx) throws InvalidSpatialArgument, InvalidShapeException {
     int idx = v.indexOf('(');
     int edx = v.lastIndexOf(')');

lucene/spatial/src/java/org/apache/lucene/spatial/query/SpatialOperation.java

@@ -20,15 +20,17 @@ package org.apache.lucene.spatial.query;
 import com.spatial4j.core.exception.InvalidSpatialArgument;
 
 import java.io.Serializable;
-import java.util.*;
+import java.util.ArrayList;
+import java.util.HashMap;
+import java.util.List;
+import java.util.Locale;
+import java.util.Map;
 
 /**
  * A clause that compares a stored geometry to a supplied geometry.
  *
  * @see <a href="http://edndoc.esri.com/arcsde/9.1/general_topics/understand_spatial_relations.htm">
  *   ESRIs docs on spatial relations</a>
- * @see <a href="http://docs.geoserver.org/latest/en/user/filter/ecql_reference.html#spatial-predicate">
- *   GeoServer ECQL Spatial Predicates</a>
  *
  * @lucene.experimental
  */