From 699b7c78437c9555fd019c58261b8b3071f1eb60 Mon Sep 17 00:00:00 2001
From: David Wayne Smiley <dsmiley@apache.org>
Date: Thu, 28 Jun 2012 19:20:06 +0000
Subject: [PATCH] LUCENE-4169 mark Lucene spatial classes as
 @lucene.experimental or @lucene.internal

git-svn-id: https://svn.apache.org/repos/asf/lucene/dev/trunk@1355120 13f79535-47bb-0310-9956-ffa450edef68
---
 .../org/apache/lucene/spatial/SimpleSpatialFieldInfo.java   | 4 +++-
 .../java/org/apache/lucene/spatial/SpatialFieldInfo.java    | 2 ++
 .../src/java/org/apache/lucene/spatial/SpatialStrategy.java | 4 ++--
 .../spatial/prefix/PointPrefixTreeFieldCacheProvider.java   | 3 +++
 .../apache/lucene/spatial/prefix/PrefixCellsTokenizer.java  | 2 +-
 .../apache/lucene/spatial/prefix/PrefixTreeStrategy.java    | 6 ++++++
 .../lucene/spatial/prefix/RecursivePrefixTreeFilter.java    | 2 ++
 .../lucene/spatial/prefix/RecursivePrefixTreeStrategy.java  | 2 ++
 .../lucene/spatial/prefix/TermQueryPrefixTreeStrategy.java  | 2 ++
 .../lucene/spatial/prefix/tree/GeohashPrefixTree.java       | 2 ++
 .../java/org/apache/lucene/spatial/prefix/tree/Node.java    | 2 ++
 .../apache/lucene/spatial/prefix/tree/QuadPrefixTree.java   | 4 +++-
 .../lucene/spatial/prefix/tree/SpatialPrefixTree.java       | 3 ++-
 .../spatial/prefix/tree/SpatialPrefixTreeFactory.java       | 1 +
 .../lucene/spatial/util/CachedDistanceValueSource.java      | 2 +-
 .../lucene/spatial/util/CachingDoubleValueSource.java       | 3 +++
 .../org/apache/lucene/spatial/util/NumericFieldInfo.java    | 1 +
 .../org/apache/lucene/spatial/util/ShapeFieldCache.java     | 3 +++
 .../apache/lucene/spatial/util/ShapeFieldCacheProvider.java | 3 +++
 .../org/apache/lucene/spatial/util/StringListTokenizer.java | 3 ++-
 .../java/org/apache/lucene/spatial/util/TruncateFilter.java | 3 +++
 .../org/apache/lucene/spatial/util/ValueSourceFilter.java   | 3 +++
 .../apache/lucene/spatial/vector/DistanceValueSource.java   | 2 +-
 .../apache/lucene/spatial/vector/TwoDoublesFieldInfo.java   | 3 +++
 .../apache/lucene/spatial/vector/TwoDoublesStrategy.java    | 3 +++
 25 files changed, 59 insertions(+), 9 deletions(-)

diff --git a/lucene/spatial/src/java/org/apache/lucene/spatial/SimpleSpatialFieldInfo.java b/lucene/spatial/src/java/org/apache/lucene/spatial/SimpleSpatialFieldInfo.java
index 04255ac6118..f6c804ce979 100644
--- a/lucene/spatial/src/java/org/apache/lucene/spatial/SimpleSpatialFieldInfo.java
+++ b/lucene/spatial/src/java/org/apache/lucene/spatial/SimpleSpatialFieldInfo.java
@@ -17,7 +17,9 @@
 
 package org.apache.lucene.spatial;
 
-
+/**
+ * @lucene.experimental
+ */
 public class SimpleSpatialFieldInfo implements SpatialFieldInfo {
 
   private final String fieldName;
diff --git a/lucene/spatial/src/java/org/apache/lucene/spatial/SpatialFieldInfo.java b/lucene/spatial/src/java/org/apache/lucene/spatial/SpatialFieldInfo.java
index 3370f0013b4..6ca122c524c 100644
--- a/lucene/spatial/src/java/org/apache/lucene/spatial/SpatialFieldInfo.java
+++ b/lucene/spatial/src/java/org/apache/lucene/spatial/SpatialFieldInfo.java
@@ -19,6 +19,8 @@ package org.apache.lucene.spatial;
 
 /**
  * Information the strategy needs for the lucene fields
+ *
+ * @lucene.experimental
  */
 public interface SpatialFieldInfo {
 }
diff --git a/lucene/spatial/src/java/org/apache/lucene/spatial/SpatialStrategy.java b/lucene/spatial/src/java/org/apache/lucene/spatial/SpatialStrategy.java
index eef1603c4e7..078eda627cd 100644
--- a/lucene/spatial/src/java/org/apache/lucene/spatial/SpatialStrategy.java
+++ b/lucene/spatial/src/java/org/apache/lucene/spatial/SpatialStrategy.java
@@ -29,6 +29,8 @@ import org.apache.lucene.search.Query;
 
 /**
  * must be thread safe
+ *
+ * @lucene.experimental
  */
 public abstract class SpatialStrategy<T extends SpatialFieldInfo> {
 
@@ -64,8 +66,6 @@ public abstract class SpatialStrategy<T extends SpatialFieldInfo> {
 
   /**
    * The value source yields a number that is proportional to the distance between the query shape and indexed data.
-   * @param args
-   * @param fieldInfo
    */
   public abstract ValueSource makeValueSource(SpatialArgs args, T fieldInfo);
 
diff --git a/lucene/spatial/src/java/org/apache/lucene/spatial/prefix/PointPrefixTreeFieldCacheProvider.java b/lucene/spatial/src/java/org/apache/lucene/spatial/prefix/PointPrefixTreeFieldCacheProvider.java
index 3088d3d4fa3..5a17741e195 100644
--- a/lucene/spatial/src/java/org/apache/lucene/spatial/prefix/PointPrefixTreeFieldCacheProvider.java
+++ b/lucene/spatial/src/java/org/apache/lucene/spatial/prefix/PointPrefixTreeFieldCacheProvider.java
@@ -23,6 +23,9 @@ import org.apache.lucene.spatial.prefix.tree.SpatialPrefixTree;
 import org.apache.lucene.spatial.util.ShapeFieldCacheProvider;
 import org.apache.lucene.util.BytesRef;
 
+/**
+ * @lucene.internal
+ */
 public class PointPrefixTreeFieldCacheProvider extends ShapeFieldCacheProvider<Point> {
 
   final SpatialPrefixTree grid; //
diff --git a/lucene/spatial/src/java/org/apache/lucene/spatial/prefix/PrefixCellsTokenizer.java b/lucene/spatial/src/java/org/apache/lucene/spatial/prefix/PrefixCellsTokenizer.java
index a552804f53f..ca59042298e 100644
--- a/lucene/spatial/src/java/org/apache/lucene/spatial/prefix/PrefixCellsTokenizer.java
+++ b/lucene/spatial/src/java/org/apache/lucene/spatial/prefix/PrefixCellsTokenizer.java
@@ -25,7 +25,7 @@ import java.io.Reader;
 
 
 /**
- *
+ * @lucene.internal
  */
 class PrefixCellsTokenizer extends Tokenizer {
   public PrefixCellsTokenizer(Reader input) {
diff --git a/lucene/spatial/src/java/org/apache/lucene/spatial/prefix/PrefixTreeStrategy.java b/lucene/spatial/src/java/org/apache/lucene/spatial/prefix/PrefixTreeStrategy.java
index 0f35b9de88f..d390ff3ea1a 100644
--- a/lucene/spatial/src/java/org/apache/lucene/spatial/prefix/PrefixTreeStrategy.java
+++ b/lucene/spatial/src/java/org/apache/lucene/spatial/prefix/PrefixTreeStrategy.java
@@ -39,6 +39,9 @@ import java.util.List;
 import java.util.Map;
 import java.util.concurrent.ConcurrentHashMap;
 
+/**
+ * @lucene.internal
+ */
 public abstract class PrefixTreeStrategy extends SpatialStrategy<SimpleSpatialFieldInfo> {
   protected final SpatialPrefixTree grid;
   private final Map<String, PointPrefixTreeFieldCacheProvider> provider = new ConcurrentHashMap<String, PointPrefixTreeFieldCacheProvider>();
@@ -73,6 +76,9 @@ public abstract class PrefixTreeStrategy extends SpatialStrategy<SimpleSpatialFi
       cells.add(grid.getNodes(ctr,grid.getMaxLevels(),false).get(0));
     }
 
+    //TODO is CellTokenStream supposed to be re-used somehow? see Uwe's comments:
+    //  http://code.google.com/p/lucene-spatial-playground/issues/detail?id=4
+
     String fname = fieldInfo.getFieldName();
     if( store ) {
       //TODO figure out how to re-use original string instead of reconstituting it.
diff --git a/lucene/spatial/src/java/org/apache/lucene/spatial/prefix/RecursivePrefixTreeFilter.java b/lucene/spatial/src/java/org/apache/lucene/spatial/prefix/RecursivePrefixTreeFilter.java
index dbdfc63afc0..964657554d1 100644
--- a/lucene/spatial/src/java/org/apache/lucene/spatial/prefix/RecursivePrefixTreeFilter.java
+++ b/lucene/spatial/src/java/org/apache/lucene/spatial/prefix/RecursivePrefixTreeFilter.java
@@ -39,6 +39,8 @@ import java.util.LinkedList;
  * 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.
+ *
+ * @lucene.internal
  */
 public class RecursivePrefixTreeFilter extends Filter {
 
diff --git a/lucene/spatial/src/java/org/apache/lucene/spatial/prefix/RecursivePrefixTreeStrategy.java b/lucene/spatial/src/java/org/apache/lucene/spatial/prefix/RecursivePrefixTreeStrategy.java
index 22e5f087cea..e7636735e8e 100644
--- a/lucene/spatial/src/java/org/apache/lucene/spatial/prefix/RecursivePrefixTreeStrategy.java
+++ b/lucene/spatial/src/java/org/apache/lucene/spatial/prefix/RecursivePrefixTreeStrategy.java
@@ -27,6 +27,8 @@ import org.apache.lucene.spatial.prefix.tree.SpatialPrefixTree;
 
 /**
  * Based on {@link RecursivePrefixTreeFilter}.
+ *
+ * @lucene.experimental
  */
 public class RecursivePrefixTreeStrategy extends PrefixTreeStrategy {
 
diff --git a/lucene/spatial/src/java/org/apache/lucene/spatial/prefix/TermQueryPrefixTreeStrategy.java b/lucene/spatial/src/java/org/apache/lucene/spatial/prefix/TermQueryPrefixTreeStrategy.java
index cfebe58c00c..f7e54b44201 100644
--- a/lucene/spatial/src/java/org/apache/lucene/spatial/prefix/TermQueryPrefixTreeStrategy.java
+++ b/lucene/spatial/src/java/org/apache/lucene/spatial/prefix/TermQueryPrefixTreeStrategy.java
@@ -33,6 +33,8 @@ import java.util.List;
 /**
  * A basic implementation using a large {@link TermsFilter} of all the nodes from
  * {@link SpatialPrefixTree#getNodes(com.spatial4j.core.shape.Shape, int, boolean)}.
+ *
+ * @lucene.experimental
  */
 public class TermQueryPrefixTreeStrategy extends PrefixTreeStrategy {
 
diff --git a/lucene/spatial/src/java/org/apache/lucene/spatial/prefix/tree/GeohashPrefixTree.java b/lucene/spatial/src/java/org/apache/lucene/spatial/prefix/tree/GeohashPrefixTree.java
index 2c576c02549..518f59880bc 100644
--- a/lucene/spatial/src/java/org/apache/lucene/spatial/prefix/tree/GeohashPrefixTree.java
+++ b/lucene/spatial/src/java/org/apache/lucene/spatial/prefix/tree/GeohashPrefixTree.java
@@ -30,6 +30,8 @@ import java.util.List;
 
 /**
  * A SpatialPrefixGrid based on Geohashes.  Uses {@link GeohashUtils} to do all the geohash work.
+ *
+ * @lucene.experimental
  */
 public class GeohashPrefixTree extends SpatialPrefixTree {
 
diff --git a/lucene/spatial/src/java/org/apache/lucene/spatial/prefix/tree/Node.java b/lucene/spatial/src/java/org/apache/lucene/spatial/prefix/tree/Node.java
index 62c7616ea88..9fe63e6cc6c 100644
--- a/lucene/spatial/src/java/org/apache/lucene/spatial/prefix/tree/Node.java
+++ b/lucene/spatial/src/java/org/apache/lucene/spatial/prefix/tree/Node.java
@@ -28,6 +28,8 @@ import java.util.List;
 
 /**
  * Represents a grid cell. These are not necessarily threadsafe, although new Cell("") (world cell) must be.
+ *
+ * @lucene.experimental
  */
 public abstract class Node implements Comparable<Node> {
   public static final byte LEAF_BYTE = '+';//NOTE: must sort before letters & numbers
diff --git a/lucene/spatial/src/java/org/apache/lucene/spatial/prefix/tree/QuadPrefixTree.java b/lucene/spatial/src/java/org/apache/lucene/spatial/prefix/tree/QuadPrefixTree.java
index e203b4a0e9d..2ed1c0ab73a 100644
--- a/lucene/spatial/src/java/org/apache/lucene/spatial/prefix/tree/QuadPrefixTree.java
+++ b/lucene/spatial/src/java/org/apache/lucene/spatial/prefix/tree/QuadPrefixTree.java
@@ -29,7 +29,9 @@ import java.util.ArrayList;
 import java.util.Collection;
 import java.util.List;
 
-
+/**
+ * @lucene.experimental
+ */
 public class QuadPrefixTree extends SpatialPrefixTree {
 
   public static class Factory extends SpatialPrefixTreeFactory {
diff --git a/lucene/spatial/src/java/org/apache/lucene/spatial/prefix/tree/SpatialPrefixTree.java b/lucene/spatial/src/java/org/apache/lucene/spatial/prefix/tree/SpatialPrefixTree.java
index 11699e510cf..20c23faa6dc 100644
--- a/lucene/spatial/src/java/org/apache/lucene/spatial/prefix/tree/SpatialPrefixTree.java
+++ b/lucene/spatial/src/java/org/apache/lucene/spatial/prefix/tree/SpatialPrefixTree.java
@@ -32,6 +32,8 @@ import java.util.List;
  * variable precision.  Each string corresponds to a spatial region.
  *
  * Implementations of this class should be thread-safe and immutable once initialized.
+ *
+ * @lucene.experimental
  */
 public abstract class SpatialPrefixTree {
 
@@ -64,7 +66,6 @@ public abstract class SpatialPrefixTree {
    * See {@link com.spatial4j.core.query.SpatialArgs#getDistPrecision()}.
    * A grid level looked up via {@link #getLevelForDistance(double)} is returned.
    *
-   * @param shape
    * @param precision 0-0.5
    * @return 1-maxLevels
    */
diff --git a/lucene/spatial/src/java/org/apache/lucene/spatial/prefix/tree/SpatialPrefixTreeFactory.java b/lucene/spatial/src/java/org/apache/lucene/spatial/prefix/tree/SpatialPrefixTreeFactory.java
index 88a1fb6b101..bb84782a559 100644
--- a/lucene/spatial/src/java/org/apache/lucene/spatial/prefix/tree/SpatialPrefixTreeFactory.java
+++ b/lucene/spatial/src/java/org/apache/lucene/spatial/prefix/tree/SpatialPrefixTreeFactory.java
@@ -24,6 +24,7 @@ import com.spatial4j.core.distance.DistanceUtils;
 import java.util.Map;
 
 /**
+ * @lucene.experimental
  */
 public abstract class SpatialPrefixTreeFactory {
 
diff --git a/lucene/spatial/src/java/org/apache/lucene/spatial/util/CachedDistanceValueSource.java b/lucene/spatial/src/java/org/apache/lucene/spatial/util/CachedDistanceValueSource.java
index 49e9ec3192a..49bb4de832a 100644
--- a/lucene/spatial/src/java/org/apache/lucene/spatial/util/CachedDistanceValueSource.java
+++ b/lucene/spatial/src/java/org/apache/lucene/spatial/util/CachedDistanceValueSource.java
@@ -28,9 +28,9 @@ import java.util.List;
 import java.util.Map;
 
 /**
- *
  * An implementation of the Lucene ValueSource model to support spatial relevance ranking.
  *
+ * @lucene.internal
  */
 public class CachedDistanceValueSource extends ValueSource {
 
diff --git a/lucene/spatial/src/java/org/apache/lucene/spatial/util/CachingDoubleValueSource.java b/lucene/spatial/src/java/org/apache/lucene/spatial/util/CachingDoubleValueSource.java
index 3842b07514c..678e2a544ce 100644
--- a/lucene/spatial/src/java/org/apache/lucene/spatial/util/CachingDoubleValueSource.java
+++ b/lucene/spatial/src/java/org/apache/lucene/spatial/util/CachingDoubleValueSource.java
@@ -25,6 +25,9 @@ import java.io.IOException;
 import java.util.HashMap;
 import java.util.Map;
 
+/**
+ * @lucene.internal
+ */
 public class CachingDoubleValueSource extends ValueSource {
 
   final ValueSource source;
diff --git a/lucene/spatial/src/java/org/apache/lucene/spatial/util/NumericFieldInfo.java b/lucene/spatial/src/java/org/apache/lucene/spatial/util/NumericFieldInfo.java
index 01084afaaca..c4d137e2f1d 100644
--- a/lucene/spatial/src/java/org/apache/lucene/spatial/util/NumericFieldInfo.java
+++ b/lucene/spatial/src/java/org/apache/lucene/spatial/util/NumericFieldInfo.java
@@ -23,6 +23,7 @@ import org.apache.lucene.index.IndexableField;
 
 /**
  * Hold some of the parameters used by solr...
+ * @lucene.experimental
  */
 public class NumericFieldInfo {
   public int precisionStep = 8; // same as solr default
diff --git a/lucene/spatial/src/java/org/apache/lucene/spatial/util/ShapeFieldCache.java b/lucene/spatial/src/java/org/apache/lucene/spatial/util/ShapeFieldCache.java
index 45b21ec6f0f..93a829f021e 100644
--- a/lucene/spatial/src/java/org/apache/lucene/spatial/util/ShapeFieldCache.java
+++ b/lucene/spatial/src/java/org/apache/lucene/spatial/util/ShapeFieldCache.java
@@ -22,6 +22,9 @@ import com.spatial4j.core.shape.Shape;
 import java.util.ArrayList;
 import java.util.List;
 
+/**
+ * @lucene.internal
+ */
 public class ShapeFieldCache<T extends Shape> {
   private List<T>[] cache;
   public int defaultLength;
diff --git a/lucene/spatial/src/java/org/apache/lucene/spatial/util/ShapeFieldCacheProvider.java b/lucene/spatial/src/java/org/apache/lucene/spatial/util/ShapeFieldCacheProvider.java
index 1eff3c3be46..4d1b906f6be 100644
--- a/lucene/spatial/src/java/org/apache/lucene/spatial/util/ShapeFieldCacheProvider.java
+++ b/lucene/spatial/src/java/org/apache/lucene/spatial/util/ShapeFieldCacheProvider.java
@@ -26,6 +26,9 @@ import java.io.IOException;
 import java.util.WeakHashMap;
 import java.util.logging.Logger;
 
+/**
+ * @lucene.internal
+ */
 public abstract class ShapeFieldCacheProvider<T extends Shape> {
   private Logger log = Logger.getLogger(getClass().getName());
 
diff --git a/lucene/spatial/src/java/org/apache/lucene/spatial/util/StringListTokenizer.java b/lucene/spatial/src/java/org/apache/lucene/spatial/util/StringListTokenizer.java
index 6c2ab437c1c..eda4e86679a 100644
--- a/lucene/spatial/src/java/org/apache/lucene/spatial/util/StringListTokenizer.java
+++ b/lucene/spatial/src/java/org/apache/lucene/spatial/util/StringListTokenizer.java
@@ -24,7 +24,8 @@ import java.io.IOException;
 import java.util.Iterator;
 
 /**
- * Put a list of strings directly into the token stream
+ * Put a list of strings directly into the token stream.
+ * @lucene.internal
  */
 public final class StringListTokenizer extends TokenStream {
 
diff --git a/lucene/spatial/src/java/org/apache/lucene/spatial/util/TruncateFilter.java b/lucene/spatial/src/java/org/apache/lucene/spatial/util/TruncateFilter.java
index bc0144341fa..5c3553c9743 100644
--- a/lucene/spatial/src/java/org/apache/lucene/spatial/util/TruncateFilter.java
+++ b/lucene/spatial/src/java/org/apache/lucene/spatial/util/TruncateFilter.java
@@ -24,6 +24,9 @@ import org.apache.lucene.analysis.tokenattributes.CharTermAttribute;
 
 import java.io.IOException;
 
+/**
+ * @lucene.internal
+ */
 public class TruncateFilter extends TokenFilter {
 
   private final int maxTokenLength;
diff --git a/lucene/spatial/src/java/org/apache/lucene/spatial/util/ValueSourceFilter.java b/lucene/spatial/src/java/org/apache/lucene/spatial/util/ValueSourceFilter.java
index 57130de3988..1a430b721b8 100644
--- a/lucene/spatial/src/java/org/apache/lucene/spatial/util/ValueSourceFilter.java
+++ b/lucene/spatial/src/java/org/apache/lucene/spatial/util/ValueSourceFilter.java
@@ -27,6 +27,9 @@ import org.apache.lucene.util.Bits;
 
 import java.io.IOException;
 
+/**
+ * @lucene.internal
+ */
 public class ValueSourceFilter extends Filter {
 
   final Filter startingFilter;
diff --git a/lucene/spatial/src/java/org/apache/lucene/spatial/vector/DistanceValueSource.java b/lucene/spatial/src/java/org/apache/lucene/spatial/vector/DistanceValueSource.java
index fd977ade540..bf17e287197 100644
--- a/lucene/spatial/src/java/org/apache/lucene/spatial/vector/DistanceValueSource.java
+++ b/lucene/spatial/src/java/org/apache/lucene/spatial/vector/DistanceValueSource.java
@@ -32,9 +32,9 @@ import java.io.IOException;
 import java.util.Map;
 
 /**
- *
  * An implementation of the Lucene ValueSource model to support spatial relevance ranking.
  *
+ * @lucene.internal
  */
 public class DistanceValueSource extends ValueSource {
 
diff --git a/lucene/spatial/src/java/org/apache/lucene/spatial/vector/TwoDoublesFieldInfo.java b/lucene/spatial/src/java/org/apache/lucene/spatial/vector/TwoDoublesFieldInfo.java
index 7801d5a8be7..a1ddfc20792 100644
--- a/lucene/spatial/src/java/org/apache/lucene/spatial/vector/TwoDoublesFieldInfo.java
+++ b/lucene/spatial/src/java/org/apache/lucene/spatial/vector/TwoDoublesFieldInfo.java
@@ -19,6 +19,9 @@ package org.apache.lucene.spatial.vector;
 
 import org.apache.lucene.spatial.SpatialFieldInfo;
 
+/**
+ * @lucene.experimental
+ */
 public class TwoDoublesFieldInfo implements SpatialFieldInfo {
 
   public static final String SUFFIX_X = "__x";
diff --git a/lucene/spatial/src/java/org/apache/lucene/spatial/vector/TwoDoublesStrategy.java b/lucene/spatial/src/java/org/apache/lucene/spatial/vector/TwoDoublesStrategy.java
index 1276e0c82b2..3e419de6c68 100644
--- a/lucene/spatial/src/java/org/apache/lucene/spatial/vector/TwoDoublesStrategy.java
+++ b/lucene/spatial/src/java/org/apache/lucene/spatial/vector/TwoDoublesStrategy.java
@@ -38,6 +38,9 @@ import org.apache.lucene.spatial.util.CachingDoubleValueSource;
 import org.apache.lucene.spatial.util.NumericFieldInfo;
 import org.apache.lucene.spatial.util.ValueSourceFilter;
 
+/**
+ * @lucene.experimental
+ */
 public class TwoDoublesStrategy extends SpatialStrategy<TwoDoublesFieldInfo> {
 
   private final NumericFieldInfo finfo;