LUCENE-7076: Improve MIGRATE.txt/Point javadocs

lucene/MIGRATE.txt

@@ -74,10 +74,12 @@ would be equivalent to the following code with the old setBoost API:
   float boost = ...;
   q.setBoost(q.getBoost() * boost);
 
-## DimensionalValues replaces NumericField (LUCENE-6917)
+# PointValues replaces NumericField (LUCENE-6917)
 
-DimensionalValues provides faster indexing and searching, a smaller
+PointValues provides faster indexing and searching, a smaller
-index size, and less heap used at search time.  The numeric fields
+index size, and less heap used at search time. See org.apache.lucene.index.PointValues
-(IntField, FloatField, LongField, DoubleField) and NumericRangeQuery
+for an introduction. 
-have been moved to the backward-codecs module and prefixed with
+
-Legacy.
+Legacy numeric encodings from previous versions of Lucene are
+deprecated as LegacyIntField, LegacyFloatField, LegacyLongField, and LegacyDoubleField,
+and can be searched with LegacyNumericRangeQuery.

lucene/core/src/java/org/apache/lucene/document/BinaryPoint.java

@@ -19,6 +19,7 @@ package org.apache.lucene.document;
 import java.util.Arrays;
 import java.util.Comparator;
 
+import org.apache.lucene.index.PointValues;
 import org.apache.lucene.search.MatchNoDocsQuery;
 import org.apache.lucene.search.PointInSetQuery;
 import org.apache.lucene.search.PointRangeQuery;
@@ -40,6 +41,7 @@ import org.apache.lucene.util.StringHelper;
  *   <li>{@link #newRangeQuery(String, byte[], byte[])} for matching a 1D range.
  *   <li>{@link #newRangeQuery(String, byte[][], byte[][])} for matching points/ranges in n-dimensional space.
  * </ul> 
+ * @see PointValues
  */
 public final class BinaryPoint extends Field {
 

lucene/core/src/java/org/apache/lucene/document/DoublePoint.java

@@ -18,6 +18,7 @@ package org.apache.lucene.document;
 
 import java.util.Arrays;
 
+import org.apache.lucene.index.PointValues;
 import org.apache.lucene.search.PointInSetQuery;
 import org.apache.lucene.search.PointRangeQuery;
 import org.apache.lucene.search.Query;
@@ -38,6 +39,7 @@ import org.apache.lucene.util.NumericUtils;
  *   <li>{@link #newRangeQuery(String, double, double)} for matching a 1D range.
  *   <li>{@link #newRangeQuery(String, double[], double[])} for matching points/ranges in n-dimensional space.
  * </ul> 
+ * @see PointValues
  */
 public final class DoublePoint extends Field {
 

lucene/core/src/java/org/apache/lucene/document/FloatPoint.java

@@ -18,6 +18,7 @@ package org.apache.lucene.document;
 
 import java.util.Arrays;
 
+import org.apache.lucene.index.PointValues;
 import org.apache.lucene.search.PointInSetQuery;
 import org.apache.lucene.search.PointRangeQuery;
 import org.apache.lucene.search.Query;
@@ -38,6 +39,7 @@ import org.apache.lucene.util.NumericUtils;
  *   <li>{@link #newRangeQuery(String, float, float)} for matching a 1D range.
  *   <li>{@link #newRangeQuery(String, float[], float[])} for matching points/ranges in n-dimensional space.
  * </ul>
+ * @see PointValues
  */
 public final class FloatPoint extends Field {
 

lucene/core/src/java/org/apache/lucene/document/IntPoint.java

@@ -18,6 +18,7 @@ package org.apache.lucene.document;
 
 import java.util.Arrays;
 
+import org.apache.lucene.index.PointValues;
 import org.apache.lucene.search.PointInSetQuery;
 import org.apache.lucene.search.PointRangeQuery;
 import org.apache.lucene.search.Query;
@@ -38,6 +39,7 @@ import org.apache.lucene.util.NumericUtils;
  *   <li>{@link #newRangeQuery(String, int, int)} for matching a 1D range.
  *   <li>{@link #newRangeQuery(String, int[], int[])} for matching points/ranges in n-dimensional space.
  * </ul>
+ * @see PointValues
  */
 public final class IntPoint extends Field {
 

lucene/core/src/java/org/apache/lucene/document/LongPoint.java

@@ -18,6 +18,7 @@ package org.apache.lucene.document;
 
 import java.util.Arrays;
 
+import org.apache.lucene.index.PointValues;
 import org.apache.lucene.search.PointInSetQuery;
 import org.apache.lucene.search.PointRangeQuery;
 import org.apache.lucene.search.Query;
@@ -38,6 +39,7 @@ import org.apache.lucene.util.NumericUtils;
  *   <li>{@link #newRangeQuery(String, long, long)} for matching a 1D range.
  *   <li>{@link #newRangeQuery(String, long[], long[])} for matching points/ranges in n-dimensional space.
  * </ul>
+ * @see PointValues
  */
 public final class LongPoint extends Field {
 

lucene/core/src/java/org/apache/lucene/index/PointValues.java

@@ -17,17 +17,65 @@
 package org.apache.lucene.index;
 
 import java.io.IOException;
+import java.math.BigInteger;
+import java.net.InetAddress;
 
 import org.apache.lucene.document.BinaryPoint;
 import org.apache.lucene.document.DoublePoint;
+import org.apache.lucene.document.Field;
+import org.apache.lucene.document.FieldType;
 import org.apache.lucene.document.FloatPoint;
 import org.apache.lucene.document.IntPoint;
 import org.apache.lucene.document.LongPoint;
 import org.apache.lucene.util.bkd.BKDWriter;
 
-/** Allows recursively visiting point values indexed with {@link IntPoint},
+/** 
- *  {@link FloatPoint}, {@link LongPoint}, {@link DoublePoint}
+ * Access to indexed numeric values.
- *  or {@link BinaryPoint}.
+ * <p>
+ * Points represent numeric values and are indexed differently than ordinary text. Instead of an inverted index, 
+ * points are indexed with datastructures such as <a href="https://en.wikipedia.org/wiki/K-d_tree">KD-trees</a>. 
+ * These structures are optimized for operations such as <i>range</i>, <i>distance</i>, <i>nearest-neighbor</i>, 
+ * and <i>point-in-polygon</i> queries. 
+ * <h1>Basic Point Types</h1>
+ * <table summary="Basic point types in Java and Lucene">
+ *   <tr><th>Java type</th><th>Lucene class</th></tr>
+ *   <tr><td>{@code int}</td><td>{@link IntPoint}</td></tr>
+ *   <tr><td>{@code long}</td><td>{@link LongPoint}</td></tr>
+ *   <tr><td>{@code float}</td><td>{@link FloatPoint}</td></tr>
+ *   <tr><td>{@code double}</td><td>{@link DoublePoint}</td></tr>
+ *   <tr><td>{@code byte[]}</td><td>{@link BinaryPoint}</td></tr>
+ *   <tr><td>{@link BigInteger}</td><td><a href="{@docRoot}/../sandbox/org/apache/lucene/document/BigIntegerPoint.html">BigIntegerPoint</a>*</td></tr>
+ *   <tr><td>{@link InetAddress}</td><td><a href="{@docRoot}/../sandbox/org/apache/lucene/document/InetAddressPoint.html">InetAddressPoint</a>*</td></tr>
+ * </table>
+ * * in the <i>lucene-sandbox</i> jar<br>
+ * <p>
+ * Basic Lucene point types behave like their java peers: for example {@link IntPoint} represents a signed 32-bit 
+ * {@link Integer}, supporting values ranging from {@link Integer#MIN_VALUE} to {@link Integer#MAX_VALUE}, ordered
+ * consistent with {@link Integer#compareTo(Integer)}. In addition to indexing support, point classes also contain 
+ * static methods (such as {@link IntPoint#newRangeQuery(String, int, int)}) for creating common queries. For example:
+ * <pre class="prettyprint">
+ *   // add year 1970 to document
+ *   document.add(new IntPoint("year", 1970));
+ *   // index document
+ *   writer.addDocument(document);
+ *   ...
+ *   // issue range query of 1960-1980
+ *   Query query = IntPoint.newRangeQuery("year", 1960, 1980);
+ *   TopDocs docs = searcher.search(query, ...);
+ * </pre>
+ * <h1>Geospatial Point Types</h1>
+ * Although basic point types such as {@link DoublePoint} support points in multi-dimensional space too, Lucene has
+ * specialized classes for location data. These classes are optimized for location data: they are more space-efficient and 
+ * support special operations such as <i>distance</i> and <i>polygon</i> queries. There are currently two implementations:
+ * <br>
+ * <ol>
+ *   <li><a href="{@docRoot}/../sandbox/org/apache/lucene/document/LatLonPoint.html">LatLonPoint</a> in <i>lucene-sandbox</i>: indexes {@code (latitude,longitude)} as {@code (x,y)} in two-dimensional space.
+ *   <li><a href="{@docRoot}/../spatial3d/org/apache/lucene/spatial3d/Geo3DPoint.html">Geo3DPoint</a>* in <i>lucene-spatial3d</i>: indexes {@code (latitude,longitude)} as {@code (x,y,z)} in three-dimensional space.
+ * </ol>
+ * * does <b>not</b> support altitude, 3D here means "uses three dimensions under-the-hood"<br>
+ * <h1>Advanced usage</h1>
+ * Custom structures can be created on top of single- or multi- dimensional basic types, on top of 
+ * {@link BinaryPoint} for more flexibility, or via custom {@link Field} subclasses.
  *
  *  @lucene.experimental */
 public abstract class PointValues {

lucene/core/src/java/org/apache/lucene/search/PointInSetQuery.java

@@ -16,15 +16,10 @@
  */
 package org.apache.lucene.search;
 
-
 import java.io.IOException;
 import java.util.Arrays;
 
-import org.apache.lucene.document.BinaryPoint;
-import org.apache.lucene.document.DoublePoint;
-import org.apache.lucene.document.FloatPoint;
 import org.apache.lucene.document.IntPoint;
-import org.apache.lucene.document.LongPoint;
 import org.apache.lucene.index.FieldInfo;
 import org.apache.lucene.index.LeafReader;
 import org.apache.lucene.index.LeafReaderContext;
@@ -48,13 +43,7 @@ import org.apache.lucene.util.StringHelper;
  * create range queries for lucene's standard {@code Point} types, refer to factory
  * methods on those classes, e.g. {@link IntPoint#newSetQuery IntPoint.newSetQuery()} for 
  * fields indexed with {@link IntPoint}.
-
+ * @see PointValues
- * @see IntPoint
- * @see LongPoint
- * @see FloatPoint
- * @see DoublePoint
- * @see BinaryPoint 
- *
  * @lucene.experimental */
 
 public abstract class PointInSetQuery extends Query {

lucene/core/src/java/org/apache/lucene/search/PointRangeQuery.java

@@ -23,11 +23,7 @@ import java.util.Objects;
 import org.apache.lucene.index.PointValues;
 import org.apache.lucene.index.PointValues.IntersectVisitor;
 import org.apache.lucene.index.PointValues.Relation;
-import org.apache.lucene.document.BinaryPoint; // javadocs
-import org.apache.lucene.document.DoublePoint; // javadocs
-import org.apache.lucene.document.FloatPoint;  // javadocs
 import org.apache.lucene.document.IntPoint;    // javadocs
-import org.apache.lucene.document.LongPoint;   // javadocs
 import org.apache.lucene.index.FieldInfo;
 import org.apache.lucene.index.LeafReader;
 import org.apache.lucene.index.LeafReaderContext;
@@ -44,12 +40,7 @@ import org.apache.lucene.util.StringHelper;
  * fields indexed with {@link IntPoint}.
  * <p>
  * For a single-dimensional field this query is a simple range query; in a multi-dimensional field it's a box shape.
- * @see IntPoint
+ * @see PointValues
- * @see LongPoint
- * @see FloatPoint
- * @see DoublePoint
- * @see BinaryPoint 
- *
  * @lucene.experimental
  */
 public abstract class PointRangeQuery extends Query {

lucene/sandbox/src/java/org/apache/lucene/document/BigIntegerPoint.java

@@ -19,6 +19,7 @@ package org.apache.lucene.document;
 import java.math.BigInteger;
 import java.util.Arrays;
 
+import org.apache.lucene.index.PointValues;
 import org.apache.lucene.search.PointInSetQuery;
 import org.apache.lucene.search.PointRangeQuery;
 import org.apache.lucene.search.Query;
@@ -39,6 +40,7 @@ import org.apache.lucene.util.NumericUtils;
  *   <li>{@link #newRangeQuery(String, BigInteger, BigInteger)} for matching a 1D range.
  *   <li>{@link #newRangeQuery(String, BigInteger[], BigInteger[])} for matching points/ranges in n-dimensional space.
  * </ul>
+ * @see PointValues
  */
 public class BigIntegerPoint extends Field {
 

lucene/sandbox/src/java/org/apache/lucene/document/InetAddressPoint.java

@@ -20,6 +20,7 @@ import java.net.InetAddress;
 import java.net.UnknownHostException;
 import java.util.Arrays;
 
+import org.apache.lucene.index.PointValues;
 import org.apache.lucene.search.PointInSetQuery;
 import org.apache.lucene.search.PointRangeQuery;
 import org.apache.lucene.search.Query;
@@ -43,6 +44,7 @@ import org.apache.lucene.util.BytesRef;
  * This field supports both IPv4 and IPv6 addresses: IPv4 addresses are converted
  * to <a href="https://tools.ietf.org/html/rfc4291#section-2.5.5">IPv4-Mapped IPv6 Addresses</a>:
  * indexing {@code 1.2.3.4} is the same as indexing {@code ::FFFF:1.2.3.4}.
+ * @see PointValues
  */
 public class InetAddressPoint extends Field {
 

lucene/sandbox/src/java/org/apache/lucene/document/LatLonPoint.java

@@ -20,6 +20,7 @@ import org.apache.lucene.util.BytesRef;
 import org.apache.lucene.util.NumericUtils;
 
 import org.apache.lucene.index.FieldInfo;
+import org.apache.lucene.index.PointValues;
 import org.apache.lucene.search.BooleanClause;
 import org.apache.lucene.search.BooleanQuery;
 import org.apache.lucene.search.ConstantScoreQuery;
@@ -43,6 +44,7 @@ import org.apache.lucene.spatial.util.GeoUtils;
  * <p>
  * <b>WARNING</b>: Values are indexed with some loss of precision, incurring up to 1E-7 error from the
  * original {@code double} values. 
+ * @see PointValues
  */
 // TODO ^^^ that is very sandy and hurts the API, usage, and tests tremendously, because what the user passes
 // to the field is not actually what gets indexed. Float would be 1E-5 error vs 1E-7, but it might be

lucene/spatial3d/src/java/org/apache/lucene/spatial3d/Geo3DPoint.java

@@ -18,6 +18,7 @@ package org.apache.lucene.spatial3d;
 
 import org.apache.lucene.document.Field;
 import org.apache.lucene.document.FieldType;
+import org.apache.lucene.index.PointValues;
 import org.apache.lucene.spatial3d.geom.GeoPoint;
 import org.apache.lucene.spatial3d.geom.GeoShape;
 import org.apache.lucene.spatial3d.geom.PlanetModel;
@@ -34,7 +35,7 @@ import org.apache.lucene.util.NumericUtils;
  * <ul>
  *   <li>{@link #newShapeQuery newShapeQuery()} for matching all points inside a specified shape
  * </ul>
- *
+ * @see PointValues
  *  @lucene.experimental */
 public final class Geo3DPoint extends Field {