Enhance documentation for spatial. Still need to properly document the Strategy subclasses thoroughly.

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

lucene/spatial/src/java/org/apache/lucene/spatial/prefix/PointPrefixTreeFieldCacheProvider.java

@@ -40,8 +40,7 @@ public class PointPrefixTreeFieldCacheProvider extends ShapeFieldCacheProvider<P
     this.grid = grid;
   }
 
-  //A kluge that this is a field
+  private Node scanCell = null;//re-used in readShape to save GC
-  private Node scanCell = null;
 
   @Override
   protected Point readShape(BytesRef term) {

lucene/spatial/src/java/org/apache/lucene/spatial/prefix/RecursivePrefixTreeFilter.java

@@ -34,11 +34,13 @@ import java.io.IOException;
 import java.util.LinkedList;
 
 /**
- * Performs a spatial intersection filter against a field indexed with {@link SpatialPrefixTree}, a Trie.
+ * Performs a spatial intersection filter between a query shape and a field indexed with {@link SpatialPrefixTree}, a Trie.
  * SPT yields terms (grids) at length 1 and at greater lengths corresponding to greater precisions.
  * This filter recursively traverses each grid length and uses methods on {@link Shape} to efficiently know
  * that all points at a prefix fit in the shape or not to either short-circuit unnecessary traversals or to efficiently
- * load all enclosed points.
+ * load all enclosed points.  If no indexed data lies in a portion of the shape
+ * then that portion of the query shape is quickly passed over without
+ * decomposing the shape unnecessarily.
  *
  * @lucene.internal
  */

lucene/spatial/src/java/org/apache/lucene/spatial/prefix/TermQueryPrefixTreeStrategy.java

@@ -30,9 +30,14 @@ import org.apache.lucene.spatial.query.UnsupportedSpatialOperation;
 import java.util.List;
 
 /**
- * A basic implementation using a large {@link TermsFilter} of all the nodes from
+ * A basic implementation of {@link PrefixTreeStrategy} using a large
+ * {@link TermsFilter} of all the nodes from
  * {@link SpatialPrefixTree#getNodes(com.spatial4j.core.shape.Shape, int, boolean)}.
- *
+ * It only supports the search of indexed Point shapes.
+ * <p />
+ * The precision of query shapes is an important factor in using this Strategy.
+ * If the precision is too precise then it will result in many terms which will
+ * amount to a slower query.
  * @lucene.experimental
  */
 public class TermQueryPrefixTreeStrategy extends PrefixTreeStrategy {

lucene/spatial/src/java/org/apache/lucene/spatial/prefix/tree/GeohashPrefixTree.java

@@ -29,7 +29,9 @@ import java.util.List;
 
 
 /**
- * A SpatialPrefixGrid based on Geohashes.  Uses {@link GeohashUtils} to do all the geohash work.
+ * A {@link SpatialPrefixTree} based on
+ * <a href="http://en.wikipedia.org/wiki/Geohash">Geohashes</a>.
+ * Uses {@link GeohashUtils} to do all the geohash work.
  *
  * @lucene.experimental
  */

lucene/spatial/src/java/org/apache/lucene/spatial/prefix/tree/Node.java

@@ -27,7 +27,7 @@ import java.util.Collections;
 import java.util.List;
 
 /**
- * Represents a grid cell. These are not necessarily threadsafe, although new Cell("") (world cell) must be.
+ * Represents a grid cell. These are not necessarily thread-safe, although new Cell("") (world cell) must be.
  *
  * @lucene.experimental
  */

lucene/spatial/src/java/org/apache/lucene/spatial/prefix/tree/QuadPrefixTree.java

@@ -31,8 +31,9 @@ import java.util.List;
 import java.util.Locale;
 
 /**
- * Implementation of {@link SpatialPrefixTree} which uses a quad tree
+ * A {@link SpatialPrefixTree} which uses a
- * (http://en.wikipedia.org/wiki/Quadtree)
+ * <a href="http://en.wikipedia.org/wiki/Quadtree">quad tree</a> in which an
+ * indexed term will be generated for each node, 'A', 'B', 'C', 'D'.
  *
  * @lucene.experimental
  */

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

@@ -24,6 +24,7 @@ import com.spatial4j.core.shape.Shape;
 
 /**
  * Principally holds the query {@link Shape} and the {@link SpatialOperation}.
+ * It's used as an argument to some methods on {@link org.apache.lucene.spatial.SpatialStrategy}.
  *
  * @lucene.experimental
  */

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

@@ -34,7 +34,7 @@ import java.util.StringTokenizer;
  * ShapeReadWriter#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
+ *   Intersects(-10,20,-8,22) distErrPct=0.025
  * </pre>
  * <p/>
  * In the future it would be good to support something at least semi-standardized like a

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

@@ -18,7 +18,7 @@ package org.apache.lucene.spatial.query;
  */
 
 /**
- * Exception thrown when the strategy cannot implement the requested operation.
+ * Exception thrown when the {@link org.apache.lucene.spatial.SpatialStrategy} cannot implement the requested operation.
  * @lucene.experimental
  */
 public class UnsupportedSpatialOperation extends UnsupportedOperationException {

lucene/spatial/src/java/org/apache/lucene/spatial/util/ShapeFieldCache.java

@@ -24,7 +24,10 @@ import java.util.List;
 
 /**
  * Bounded Cache of Shapes associated with docIds.  Note, multiple Shapes can be
- * associated with a given docId
+ * associated with a given docId.
+ * <p>
+ * WARNING: This class holds the data in an extremely inefficient manner as all Points are in memory as objects and they
+ * are stored in many ArrayLists (one per document).  So it works but doesn't scale.  It will be replaced in the future.
  *
  * @lucene.internal
  */

lucene/spatial/src/java/org/apache/lucene/spatial/util/ValueSourceFilter.java

@@ -28,11 +28,12 @@ import org.apache.lucene.util.Bits;
 import java.io.IOException;
 
 /**
- * Filter that matches all documents where a valuesource is
+ * Filter that matches all documents where a ValueSource is
  * in between a range of <code>min</code> and <code>max</code> inclusive.
  * @lucene.internal
  */
 public class ValueSourceFilter extends Filter {
+  //TODO see https://issues.apache.org/jira/browse/LUCENE-4251  (move out of spatial & improve)
 
   final Filter startingFilter;
   final ValueSource source;

lucene/spatial/src/java/org/apache/lucene/spatial/vector/DistanceValueSource.java

@@ -30,7 +30,8 @@ import java.io.IOException;
 import java.util.Map;
 
 /**
- * An implementation of the Lucene ValueSource model that returns the distance.
+ * An implementation of the Lucene ValueSource model that returns the distance
+ * for a {@link PointVectorStrategy}.
  *
  * @lucene.internal
  */

solr/core/src/java/org/apache/solr/schema/AbstractSpatialFieldType.java

@@ -47,6 +47,11 @@ import java.io.IOException;
 import java.util.Map;
 import java.util.concurrent.ConcurrentHashMap;
 
+/**
+ * Abstract base class for Solr FieldTypes based on a Lucene 4 {@link SpatialStrategy}.
+ *
+ * @lucene.experimental
+ */
 public abstract class AbstractSpatialFieldType<T extends SpatialStrategy> extends FieldType {
 
   /** A local-param with one of "none" (default), "distance", or "recipDistance". */

solr/core/src/java/org/apache/solr/schema/AbstractSpatialPrefixTreeFieldType.java

@@ -25,6 +25,10 @@ import org.apache.solr.util.MapListener;
 
 import java.util.Map;
 
+/**
+ * @see PrefixTreeStrategy
+ * @lucene.experimental
+ */
 public abstract class AbstractSpatialPrefixTreeFieldType<T extends PrefixTreeStrategy> extends AbstractSpatialFieldType<T> {
 
   /** @see org.apache.lucene.spatial.prefix.RecursivePrefixTreeStrategy#setDefaultFieldValuesArrayLen(int)  */

solr/core/src/java/org/apache/solr/schema/SpatialPointVectorFieldType.java

@@ -23,7 +23,10 @@ import java.util.ArrayList;
 import java.util.List;
 import java.util.Map;
 
-
+/**
+ * @see PointVectorStrategy
+ * @lucene.experimental
+ */
 public class SpatialPointVectorFieldType extends AbstractSpatialFieldType<PointVectorStrategy> implements SchemaAware {
 
   protected String numberFieldName = "tdouble";//in example schema defaults to non-zero precision step -- a good choice

solr/core/src/java/org/apache/solr/schema/SpatialRecursivePrefixTreeFieldType.java

@@ -21,6 +21,10 @@ import org.apache.lucene.spatial.prefix.RecursivePrefixTreeStrategy;
 
 import java.util.Map;
 
+/**
+ * @see RecursivePrefixTreeStrategy
+ * @lucene.experimental
+ */
 public class SpatialRecursivePrefixTreeFieldType extends AbstractSpatialPrefixTreeFieldType<RecursivePrefixTreeStrategy> {
 
   /** @see RecursivePrefixTreeStrategy#setPrefixGridScanLevel(int) */

solr/core/src/java/org/apache/solr/schema/SpatialTermQueryPrefixTreeFieldType.java

@@ -19,6 +19,10 @@ package org.apache.solr.schema;
 
 import org.apache.lucene.spatial.prefix.TermQueryPrefixTreeStrategy;
 
+/**
+ * @see TermQueryPrefixTreeStrategy
+ * @lucene.experimental
+ */
 public class SpatialTermQueryPrefixTreeFieldType extends AbstractSpatialPrefixTreeFieldType<TermQueryPrefixTreeStrategy> {
 
   @Override