LUCENE-7157: Update API javadoc and Polygon method visibilities

lucene/core/src/java/org/apache/lucene/geo/Polygon.java

@@ -20,6 +20,16 @@ import java.util.Arrays;
 
 /**
  * Represents a closed polygon on the earth's surface.
+ * <p>
+ * NOTES:
+ * <ol>
+ *   <li>Coordinates must be in clockwise order, except for holes. Holes must be in counter-clockwise order.
+ *   <li>The polygon must be closed: the first and last coordinates need to have the same values.
+ *   <li>The polygon must not be self-crossing, otherwise may result in unexpected behavior.
+ *   <li>All latitude/longitude values must be in decimal degrees.
+ *   <li>Polygons cannot cross the 180th meridian. Instead, use two polygons: one on each side.
+ *   <li>For more advanced GeoSpatial indexing and query operations see the {@code spatial-extras} module
+ * </ol>
  * @lucene.experimental
  */
 public final class Polygon {

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

@@ -339,13 +339,12 @@ public class LatLonPoint extends Field {
   }
   
   /** 
-   * Create a query for matching a polygon.
+   * Create a query for matching one or more polygons.
-   * <p>
-   * The supplied {@code polygon} must be clockwise or counter-clockwise.
    * @param field field name. must not be null.
    * @param polygons array of polygons. must not be null or empty
    * @return query matching points within this polygon
    * @throws IllegalArgumentException if {@code field} is null, {@code polygons} is null or empty
+   * @see Polygon
    */
   public static Query newPolygonQuery(String field, Polygon... polygons) {
     return new LatLonPointInPolygonQuery(field, polygons);

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

@@ -55,8 +55,7 @@ final class LatLonPointInPolygonQuery extends Query {
   final String field;
   final Polygon[] polygons;
 
-  /** The lats/lons must be clockwise or counter-clockwise. */
+  LatLonPointInPolygonQuery(String field, Polygon[] polygons) {
-  public LatLonPointInPolygonQuery(String field, Polygon[] polygons) {
     if (field == null) {
       throw new IllegalArgumentException("field must not be null");
     }

lucene/spatial/src/java/org/apache/lucene/spatial/geopoint/search/GeoPointInPolygonQuery.java

@@ -36,13 +36,7 @@ import org.apache.lucene.geo.Polygon;
  * term is passed to the final point in polygon check. All value comparisons are subject
  * to the same precision tolerance defined in {@value GeoEncodingUtils#TOLERANCE}
  *
- * <p>NOTES:
+ * @see Polygon
- *    1.  The polygon coordinates need to be in either clockwise or counter-clockwise order.
- *    2.  The polygon must not be self-crossing, otherwise the query may result in unexpected behavior
- *    3.  All latitude/longitude values must be in decimal degrees.
- *    4.  Complex computational geometry (e.g., dateline wrapping) is not supported
- *    5.  For more advanced GeoSpatial indexing and query operations see spatial module
- *
  * @lucene.experimental
  */
 public final class GeoPointInPolygonQuery extends GeoPointInBBoxQuery {
@@ -79,7 +73,7 @@ public final class GeoPointInPolygonQuery extends GeoPointInBBoxQuery {
 
   /** 
    * Constructs a new GeoPolygonQuery that will match encoded {@link org.apache.lucene.spatial.geopoint.document.GeoPointField} terms
-   * that fall within or on the boundary of the polygon defined by the input parameters. 
+   * that fall within or on the boundary of the polygons defined by the input parameters. 
    */
   public GeoPointInPolygonQuery(String field, TermEncoding termEncoding, Polygon... polygons) {
     this(field, termEncoding, Rectangle.fromPolygon(polygons), polygons);