Index: contrib/spatial/src/java/org/apache/lucene/spatial/tier/projections/IProjector.java
===================================================================
--- contrib/spatial/src/java/org/apache/lucene/spatial/tier/projections/IProjector.java	(revision 810654)
+++ contrib/spatial/src/java/org/apache/lucene/spatial/tier/projections/IProjector.java	(working copy)
@@ -17,6 +17,11 @@
  
 package org.apache.lucene.spatial.tier.projections;
 
+/**
+ * <p><font color="red"><b>NOTE:</b> This API is still in
+ * flux and might change in incompatible ways in the next
+ * release.</font>
+ */
 public interface IProjector {
   public String coordsAsString(double latitude, double longitude);
   public double[] coords(double latitude, double longitude);
Index: contrib/spatial/src/java/org/apache/lucene/spatial/tier/projections/SinusoidalProjector.java
===================================================================
--- contrib/spatial/src/java/org/apache/lucene/spatial/tier/projections/SinusoidalProjector.java	(revision 810654)
+++ contrib/spatial/src/java/org/apache/lucene/spatial/tier/projections/SinusoidalProjector.java	(working copy)
@@ -20,7 +20,10 @@
 /**
  * Based on Sinusoidal Projections
  * Project a latitude / longitude on a 2D cartisian map
- * 
+ *
+ * <p><font color="red"><b>NOTE:</b> This API is still in
+ * flux and might change in incompatible ways in the next
+ * release.</font>
  */
 public class SinusoidalProjector implements IProjector {
 
Index: contrib/spatial/src/java/org/apache/lucene/spatial/tier/projections/CartesianTierPlotter.java
===================================================================
--- contrib/spatial/src/java/org/apache/lucene/spatial/tier/projections/CartesianTierPlotter.java	(revision 810654)
+++ contrib/spatial/src/java/org/apache/lucene/spatial/tier/projections/CartesianTierPlotter.java	(working copy)
@@ -18,7 +18,9 @@
 package org.apache.lucene.spatial.tier.projections;
 
 /**
- * 
+ * <p><font color="red"><b>NOTE:</b> This API is still in
+ * flux and might change in incompatible ways in the next
+ * release.</font>
  */
 public class CartesianTierPlotter {
   public static final String DEFALT_FIELD_PREFIX = "_tier_";
Index: contrib/spatial/src/java/org/apache/lucene/spatial/tier/CartesianShapeFilter.java
===================================================================
--- contrib/spatial/src/java/org/apache/lucene/spatial/tier/CartesianShapeFilter.java	(revision 810654)
+++ contrib/spatial/src/java/org/apache/lucene/spatial/tier/CartesianShapeFilter.java	(working copy)
@@ -28,6 +28,11 @@
 import org.apache.lucene.util.NumericUtils;
 import org.apache.lucene.util.OpenBitSet;
 
+/**
+ * <p><font color="red"><b>NOTE:</b> This API is still in
+ * flux and might change in incompatible ways in the next
+ * release.</font>
+ */
 public class CartesianShapeFilter extends Filter {
 
   /**
Index: contrib/spatial/src/java/org/apache/lucene/spatial/tier/DistanceFilter.java
===================================================================
--- contrib/spatial/src/java/org/apache/lucene/spatial/tier/DistanceFilter.java	(revision 810654)
+++ contrib/spatial/src/java/org/apache/lucene/spatial/tier/DistanceFilter.java	(working copy)
@@ -23,6 +23,11 @@
 import org.apache.lucene.search.Filter;
 import org.apache.lucene.spatial.tier.DistanceHandler.Precision;
 
+/**
+ * <p><font color="red"><b>NOTE:</b> This API is still in
+ * flux and might change in incompatible ways in the next
+ * release.</font>
+ */
 public abstract class DistanceFilter extends Filter {
 
   final protected Filter startingFilter;
Index: contrib/spatial/src/java/org/apache/lucene/spatial/tier/InvalidGeoException.java
===================================================================
--- contrib/spatial/src/java/org/apache/lucene/spatial/tier/InvalidGeoException.java	(revision 810654)
+++ contrib/spatial/src/java/org/apache/lucene/spatial/tier/InvalidGeoException.java	(working copy)
@@ -17,6 +17,11 @@
 
 package org.apache.lucene.spatial.tier;
 
+/**
+ * <p><font color="red"><b>NOTE:</b> This API is still in
+ * flux and might change in incompatible ways in the next
+ * release.</font>
+ */
 public class InvalidGeoException extends Exception {
 
   /**
Index: contrib/spatial/src/java/org/apache/lucene/spatial/tier/Shape.java
===================================================================
--- contrib/spatial/src/java/org/apache/lucene/spatial/tier/Shape.java	(revision 810654)
+++ contrib/spatial/src/java/org/apache/lucene/spatial/tier/Shape.java	(working copy)
@@ -21,7 +21,9 @@
 import java.util.List;
 
 /**
- *
+ * <p><font color="red"><b>NOTE:</b> This API is still in
+ * flux and might change in incompatible ways in the next
+ * release.</font>
  */
 public class Shape {
 
Index: contrib/spatial/src/java/org/apache/lucene/spatial/tier/LatLongDistanceFilter.java
===================================================================
--- contrib/spatial/src/java/org/apache/lucene/spatial/tier/LatLongDistanceFilter.java	(revision 810654)
+++ contrib/spatial/src/java/org/apache/lucene/spatial/tier/LatLongDistanceFilter.java	(working copy)
@@ -25,6 +25,11 @@
 import org.apache.lucene.search.DocIdSet;
 
 
+/**
+ * <p><font color="red"><b>NOTE:</b> This API is still in
+ * flux and might change in incompatible ways in the next
+ * release.</font>
+ */
 public class LatLongDistanceFilter extends DistanceFilter {
 
   /**
Index: contrib/spatial/src/java/org/apache/lucene/spatial/tier/DistanceQueryBuilder.java
===================================================================
--- contrib/spatial/src/java/org/apache/lucene/spatial/tier/DistanceQueryBuilder.java	(revision 810654)
+++ contrib/spatial/src/java/org/apache/lucene/spatial/tier/DistanceQueryBuilder.java	(working copy)
@@ -24,7 +24,11 @@
 import org.apache.lucene.spatial.geohash.GeoHashDistanceFilter;
 import org.apache.lucene.misc.ChainedFilter;
 
-
+/**
+ * <p><font color="red"><b>NOTE:</b> This API is still in
+ * flux and might change in incompatible ways in the next
+ * release.</font>
+ */
 public class DistanceQueryBuilder {
 
   private static final long serialVersionUID = 1L;
Index: contrib/spatial/src/java/org/apache/lucene/spatial/tier/DistanceFieldComparatorSource.java
===================================================================
--- contrib/spatial/src/java/org/apache/lucene/spatial/tier/DistanceFieldComparatorSource.java	(revision 810654)
+++ contrib/spatial/src/java/org/apache/lucene/spatial/tier/DistanceFieldComparatorSource.java	(working copy)
@@ -24,6 +24,11 @@
 import org.apache.lucene.search.FieldComparator;
 import org.apache.lucene.search.FieldComparatorSource;
 
+/**
+ * <p><font color="red"><b>NOTE:</b> This API is still in
+ * flux and might change in incompatible ways in the next
+ * release.</font>
+ */
 public class DistanceFieldComparatorSource extends FieldComparatorSource {
 
 	private static final long serialVersionUID = 1L;
Index: contrib/spatial/src/java/org/apache/lucene/spatial/tier/DistanceHandler.java
===================================================================
--- contrib/spatial/src/java/org/apache/lucene/spatial/tier/DistanceHandler.java	(revision 810654)
+++ contrib/spatial/src/java/org/apache/lucene/spatial/tier/DistanceHandler.java	(working copy)
@@ -24,6 +24,9 @@
  * Provide a high level access point to distances
  * Used by DistanceSortSource and DistanceQuery
  *  
+ * <p><font color="red"><b>NOTE:</b> This API is still in
+ * flux and might change in incompatible ways in the next
+ * release.</font>
  *
  */
 public class DistanceHandler {
Index: contrib/spatial/src/java/org/apache/lucene/spatial/tier/CartesianPolyFilterBuilder.java
===================================================================
--- contrib/spatial/src/java/org/apache/lucene/spatial/tier/CartesianPolyFilterBuilder.java	(revision 810654)
+++ contrib/spatial/src/java/org/apache/lucene/spatial/tier/CartesianPolyFilterBuilder.java	(working copy)
@@ -29,7 +29,9 @@
 
 
 /**
- *
+ * <p><font color="red"><b>NOTE:</b> This API is still in
+ * flux and might change in incompatible ways in the next
+ * release.</font>
  */
 public class CartesianPolyFilterBuilder {
 
Index: contrib/spatial/src/java/org/apache/lucene/spatial/tier/DistanceUtils.java
===================================================================
--- contrib/spatial/src/java/org/apache/lucene/spatial/tier/DistanceUtils.java	(revision 810654)
+++ contrib/spatial/src/java/org/apache/lucene/spatial/tier/DistanceUtils.java	(working copy)
@@ -23,7 +23,11 @@
 import org.apache.lucene.spatial.geometry.shape.LLRect;
 import org.apache.lucene.spatial.geometry.shape.Rectangle;
 
-
+/**
+ * <p><font color="red"><b>NOTE:</b> This API is still in
+ * flux and might change in incompatible ways in the next
+ * release.</font>
+ */
 public class DistanceUtils {
 
   static DistanceUtils instance = new DistanceUtils();
Index: contrib/spatial/src/java/org/apache/lucene/spatial/geometry/shape/Point2D.java
===================================================================
--- contrib/spatial/src/java/org/apache/lucene/spatial/geometry/shape/Point2D.java	(revision 810654)
+++ contrib/spatial/src/java/org/apache/lucene/spatial/geometry/shape/Point2D.java	(working copy)
@@ -20,6 +20,10 @@
 
 /**
  * Point class.  This type is mutable.
+ *
+ * <p><font color="red"><b>NOTE:</b> This API is still in
+ * flux and might change in incompatible ways in the next
+ * release.</font>
  */
 public class Point2D {
   private double x;
Index: contrib/spatial/src/java/org/apache/lucene/spatial/geometry/shape/Geometry2D.java
===================================================================
--- contrib/spatial/src/java/org/apache/lucene/spatial/geometry/shape/Geometry2D.java	(revision 810654)
+++ contrib/spatial/src/java/org/apache/lucene/spatial/geometry/shape/Geometry2D.java	(working copy)
@@ -20,6 +20,10 @@
 
 /**
  * Common set of operations available on 2d shapes.
+ *
+ * <p><font color="red"><b>NOTE:</b> This API is still in
+ * flux and might change in incompatible ways in the next
+ * release.</font>
  */
 public interface Geometry2D {
   /**
Index: contrib/spatial/src/java/org/apache/lucene/spatial/geometry/shape/Rectangle.java
===================================================================
--- contrib/spatial/src/java/org/apache/lucene/spatial/geometry/shape/Rectangle.java	(revision 810654)
+++ contrib/spatial/src/java/org/apache/lucene/spatial/geometry/shape/Rectangle.java	(working copy)
@@ -20,6 +20,10 @@
 
 /**
  * Rectangle shape.  
+ *
+ * <p><font color="red"><b>NOTE:</b> This API is still in
+ * flux and might change in incompatible ways in the next
+ * release.</font>
  */
 public class Rectangle implements Geometry2D {
   private Point2D ptMin, ptMax;
Index: contrib/spatial/src/java/org/apache/lucene/spatial/geometry/shape/DistanceApproximation.java
===================================================================
--- contrib/spatial/src/java/org/apache/lucene/spatial/geometry/shape/DistanceApproximation.java	(revision 810654)
+++ contrib/spatial/src/java/org/apache/lucene/spatial/geometry/shape/DistanceApproximation.java	(working copy)
@@ -19,6 +19,10 @@
 
 /**
  * Imported from mq java client.  No changes made.
+ *
+ * <p><font color="red"><b>NOTE:</b> This API is still in
+ * flux and might change in incompatible ways in the next
+ * release.</font>
  */
 public class DistanceApproximation
 {
Index: contrib/spatial/src/java/org/apache/lucene/spatial/geometry/shape/LLRect.java
===================================================================
--- contrib/spatial/src/java/org/apache/lucene/spatial/geometry/shape/LLRect.java	(revision 810654)
+++ contrib/spatial/src/java/org/apache/lucene/spatial/geometry/shape/LLRect.java	(working copy)
@@ -24,6 +24,10 @@
 
 /**
  * Lat-long rect.  Instances are mutable.
+ *
+ * <p><font color="red"><b>NOTE:</b> This API is still in
+ * flux and might change in incompatible ways in the next
+ * release.</font>
  */
 public class LLRect {
   private LatLng ll, ur;
Index: contrib/spatial/src/java/org/apache/lucene/spatial/geometry/shape/Vector2D.java
===================================================================
--- contrib/spatial/src/java/org/apache/lucene/spatial/geometry/shape/Vector2D.java	(revision 810654)
+++ contrib/spatial/src/java/org/apache/lucene/spatial/geometry/shape/Vector2D.java	(working copy)
@@ -20,6 +20,10 @@
 
 /**
  * 2D vector
+ *
+ * <p><font color="red"><b>NOTE:</b> This API is still in
+ * flux and might change in incompatible ways in the next
+ * release.</font>
  */
 public class Vector2D {
   private double x;
Index: contrib/spatial/src/java/org/apache/lucene/spatial/geometry/shape/LineSegment.java
===================================================================
--- contrib/spatial/src/java/org/apache/lucene/spatial/geometry/shape/LineSegment.java	(revision 810654)
+++ contrib/spatial/src/java/org/apache/lucene/spatial/geometry/shape/LineSegment.java	(working copy)
@@ -20,6 +20,10 @@
 
 /**
  * 2d line segment.
+ *
+ * <p><font color="red"><b>NOTE:</b> This API is still in
+ * flux and might change in incompatible ways in the next
+ * release.</font>
  */
 public class LineSegment {
   public final Point2D A = new Point2D();
Index: contrib/spatial/src/java/org/apache/lucene/spatial/geometry/shape/IntersectCase.java
===================================================================
--- contrib/spatial/src/java/org/apache/lucene/spatial/geometry/shape/IntersectCase.java	(revision 810654)
+++ contrib/spatial/src/java/org/apache/lucene/spatial/geometry/shape/IntersectCase.java	(working copy)
@@ -17,6 +17,12 @@
 
 package org.apache.lucene.spatial.geometry.shape;
 
+/**
+ *
+ * <p><font color="red"><b>NOTE:</b> This API is still in
+ * flux and might change in incompatible ways in the next
+ * release.</font>
+ */
 public enum IntersectCase {
   WITHIN,
   CONTAINS,
Index: contrib/spatial/src/java/org/apache/lucene/spatial/geometry/shape/Ellipse.java
===================================================================
--- contrib/spatial/src/java/org/apache/lucene/spatial/geometry/shape/Ellipse.java	(revision 810654)
+++ contrib/spatial/src/java/org/apache/lucene/spatial/geometry/shape/Ellipse.java	(working copy)
@@ -20,6 +20,10 @@
 
 /**
  * Ellipse shape. From C++ gl.
+ *
+ * <p><font color="red"><b>NOTE:</b> This API is still in
+ * flux and might change in incompatible ways in the next
+ * release.</font>
  */
 public class Ellipse implements Geometry2D {
   private Point2D center;
Index: contrib/spatial/src/java/org/apache/lucene/spatial/geometry/FixedLatLng.java
===================================================================
--- contrib/spatial/src/java/org/apache/lucene/spatial/geometry/FixedLatLng.java	(revision 810654)
+++ contrib/spatial/src/java/org/apache/lucene/spatial/geometry/FixedLatLng.java	(working copy)
@@ -17,6 +17,11 @@
 
 package org.apache.lucene.spatial.geometry;
 
+/**
+ * <p><font color="red"><b>NOTE:</b> This API is still in
+ * flux and might change in incompatible ways in the next
+ * release.</font>
+ */
 public class FixedLatLng extends LatLng {
   public static final double SCALE_FACTOR=1000000;
   public static final int SCALE_FACTOR_INT=1000000;
Index: contrib/spatial/src/java/org/apache/lucene/spatial/geometry/LatLng.java
===================================================================
--- contrib/spatial/src/java/org/apache/lucene/spatial/geometry/LatLng.java	(revision 810654)
+++ contrib/spatial/src/java/org/apache/lucene/spatial/geometry/LatLng.java	(working copy)
@@ -23,7 +23,10 @@
  * point based coordinates. Instances are immutable.
  * 
  * @see FloatLatLng
- * 
+ *
+ * <p><font color="red"><b>NOTE:</b> This API is still in
+ * flux and might change in incompatible ways in the next
+ * release.</font>
  */
 public abstract class LatLng {
 
Index: contrib/spatial/src/java/org/apache/lucene/spatial/geometry/CartesianPoint.java
===================================================================
--- contrib/spatial/src/java/org/apache/lucene/spatial/geometry/CartesianPoint.java	(revision 810654)
+++ contrib/spatial/src/java/org/apache/lucene/spatial/geometry/CartesianPoint.java	(working copy)
@@ -21,6 +21,10 @@
  * Represents lat/lngs as fixed point numbers translated so that all
  * world coordinates are in the first quadrant.  The same fixed point
  * scale as is used for FixedLatLng is employed.
+ *
+ * <p><font color="red"><b>NOTE:</b> This API is still in
+ * flux and might change in incompatible ways in the next
+ * release.</font>
  */
 public class CartesianPoint {
   private int x;
Index: contrib/spatial/src/java/org/apache/lucene/spatial/geometry/FloatLatLng.java
===================================================================
--- contrib/spatial/src/java/org/apache/lucene/spatial/geometry/FloatLatLng.java	(revision 810654)
+++ contrib/spatial/src/java/org/apache/lucene/spatial/geometry/FloatLatLng.java	(working copy)
@@ -17,6 +17,11 @@
 
 package org.apache.lucene.spatial.geometry;
 
+/**
+ * <p><font color="red"><b>NOTE:</b> This API is still in
+ * flux and might change in incompatible ways in the next
+ * release.</font>
+ */
 public class FloatLatLng extends LatLng {
   private double lat;
   private double lng;
Index: contrib/spatial/src/java/org/apache/lucene/spatial/geometry/DistanceUnits.java
===================================================================
--- contrib/spatial/src/java/org/apache/lucene/spatial/geometry/DistanceUnits.java	(revision 810654)
+++ contrib/spatial/src/java/org/apache/lucene/spatial/geometry/DistanceUnits.java	(working copy)
@@ -17,6 +17,11 @@
 
 package org.apache.lucene.spatial.geometry;
 
+/**
+ * <p><font color="red"><b>NOTE:</b> This API is still in
+ * flux and might change in incompatible ways in the next
+ * release.</font>
+ */
 public enum DistanceUnits {
   MILES,
   KILOMETERS;
Index: contrib/spatial/src/java/org/apache/lucene/spatial/geohash/GeoHashDistanceFilter.java
===================================================================
--- contrib/spatial/src/java/org/apache/lucene/spatial/geohash/GeoHashDistanceFilter.java	(revision 810654)
+++ contrib/spatial/src/java/org/apache/lucene/spatial/geohash/GeoHashDistanceFilter.java	(working copy)
@@ -28,6 +28,10 @@
 import org.apache.lucene.spatial.tier.DistanceUtils;
 
 
+/** <p><font color="red"><b>NOTE:</b> This API is still in
+ * flux and might change in incompatible ways in the next
+ * release.</font>
+ */
 
 public class GeoHashDistanceFilter extends DistanceFilter {
 
Index: contrib/spatial/src/java/org/apache/lucene/spatial/geohash/GeoHashUtils.java
===================================================================
--- contrib/spatial/src/java/org/apache/lucene/spatial/geohash/GeoHashUtils.java	(revision 810654)
+++ contrib/spatial/src/java/org/apache/lucene/spatial/geohash/GeoHashUtils.java	(working copy)
@@ -22,6 +22,10 @@
 
 /**
  * Based on http://en.wikipedia.org/wiki/Geohash
+ *
+ * <p><font color="red"><b>NOTE:</b> This API is still in
+ * flux and might change in incompatible ways in the next
+ * release.</font>
  */
 public class GeoHashUtils {
 
Index: contrib/spatial/src/java/overview.html
===================================================================
--- contrib/spatial/src/java/overview.html	(revision 810654)
+++ contrib/spatial/src/java/overview.html	(working copy)
@@ -17,10 +17,30 @@
 <html>
   <head>
     <title>
-      spatial
+      Geographical filtering & sorting with Lucene
     </title>
   </head>
   <body>
-  spatial
+
+<p>This package makes it possible to filter and sort according to
+geographical constraints.  For example, filter to include only
+restaurants within 2 miles of a specified latitude/longitude, sorting
+by distance ascending.</p>
+
+<p>See <a href="http://www.nsshutdown.com/projects/lucene/whitepaper/locallucene_v2.html">here</a>
+for details on the technical approach.</p>
+
+<p>Unfortunately, this package is still very new, and has little to no
+documentation.  It's best to ask for pointers on
+java-user@lucene.apache.org, and look at the unit tests included in
+the source distribution.</p>
+
+<p>There are also known issues, eg at
+least <a href="https://issues.apache.org/jira/browse/LUCENE-1815">LUCENE-1781</a>
+and <a href="https://issues.apache.org/jira/browse/LUCENE-1815">LUCENE-1815</a>.</p>
+
+<p><font color="red"><b>NOTE:</b> This package is still in flux and
+might change in incompatible ways in the next release.</font>
+
   </body>
-</html>
\ No newline at end of file
+</html>