ensure all spatial classes have javadocs (thanks to Chris Male)

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

lucene/build.xml

@@ -256,7 +256,7 @@
       <!-- queries: problems -->
       <!-- queryparser: problems -->
       <check-missing-javadocs dir="build/docs/sandbox" level="class"/>
-      <!-- spatial: problems -->
+      <check-missing-javadocs dir="build/docs/spatial" level="class"/>
       <check-missing-javadocs dir="build/docs/suggest" level="class"/>
       <check-missing-javadocs dir="build/docs/test-framework" level="class"/>
 

lucene/spatial/src/java/org/apache/lucene/spatial/bbox/BBoxSimilarity.java

@@ -21,6 +21,8 @@ import org.apache.lucene.search.Explanation;
 import com.spatial4j.core.shape.Rectangle;
 
 /**
+ * Abstraction of the calculation used to determine how similar two Bounding Boxes are.
+ *
  * @lucene.experimental
  */
 public interface BBoxSimilarity {

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

@@ -24,6 +24,11 @@ import org.apache.lucene.spatial.util.ShapeFieldCacheProvider;
 import org.apache.lucene.util.BytesRef;
 
 /**
+ * Implementation of {@link ShapeFieldCacheProvider} designed for {@link PrefixTreeStrategy}s.
+ *
+ * Note, due to the fragmented representation of Shapes in these Strategies, this implementation
+ * can only retrieve the central {@link Point} of the original Shapes.
+ *
  * @lucene.internal
  */
 public class PointPrefixTreeFieldCacheProvider extends ShapeFieldCacheProvider<Point> {

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

@@ -37,6 +37,8 @@ import java.util.Map;
 import java.util.concurrent.ConcurrentHashMap;
 
 /**
+ * Abstract SpatialStrategy which provides common functionality for those 
+ * Strategys which use {@link SpatialPrefixTree}s
  * @lucene.internal
  */
 public abstract class PrefixTreeStrategy extends SpatialStrategy {

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

@@ -35,6 +35,9 @@ import java.util.List;
  */
 public class GeohashPrefixTree extends SpatialPrefixTree {
 
+  /**
+   * Factory for creating {@link GeohashPrefixTree} instances with useful defaults
+   */
   public static class Factory extends SpatialPrefixTreeFactory {
 
     @Override

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

@@ -31,10 +31,16 @@ import java.util.List;
 import java.util.Locale;
 
 /**
+ * Implementation of {@link SpatialPrefixTree} which uses a quad tree
+ * (http://en.wikipedia.org/wiki/Quadtree)
+ *
  * @lucene.experimental
  */
 public class QuadPrefixTree extends SpatialPrefixTree {
 
+  /**
+   * Factory for creating {@link QuadPrefixTree} instances with useful defaults
+   */
   public static class Factory extends SpatialPrefixTreeFactory {
 
     @Override

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

@@ -23,6 +23,9 @@ import com.spatial4j.core.distance.DistanceUtils;
 import java.util.Map;
 
 /**
+ * Abstract Factory for creating {@link SpatialPrefixTree} instances with useful
+ * defaults and passed on configurations defined in a Map.
+ *
  * @lucene.experimental
  */
 public abstract class SpatialPrefixTreeFactory {

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

@@ -23,6 +23,9 @@ import java.util.ArrayList;
 import java.util.List;
 
 /**
+ * Bounded Cache of Shapes associated with docIds.  Note, multiple Shapes can be
+ * associated with a given docId
+ *
  * @lucene.internal
  */
 public class ShapeFieldCache<T extends Shape> {

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

@@ -27,6 +27,12 @@ import java.util.WeakHashMap;
 import java.util.logging.Logger;
 
 /**
+ * Provides access to a {@link ShapeFieldCache} for a given {@link AtomicReader}.
+ *
+ * If a Cache does not exist for the Reader, then it is built by iterating over
+ * the all terms for a given field, reconstructing the Shape from them, and adding
+ * them to the Cache.
+ *
  * @lucene.internal
  */
 public abstract class ShapeFieldCacheProvider<T extends Shape> {

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

@@ -45,6 +45,15 @@ import org.apache.lucene.spatial.util.CachingDoubleValueSource;
 import org.apache.lucene.spatial.util.ValueSourceFilter;
 
 /**
+ * Simple {@link SpatialStrategy} which represents Points in two numeric {@link DoubleField}s.
+ *
+ * Note, currently only Points can be indexed by this Strategy.  At query time, the bounding
+ * box of the given Shape is used to create {@link NumericRangeQuery}s to efficiently
+ * find Points within the Shape.
+ *
+ * Due to the simple use of numeric fields, this Strategy provides support for sorting by
+ * distance through {@link DistanceValueSource}
+ *
  * @lucene.experimental
  */
 public class TwoDoublesStrategy extends SpatialStrategy {