Comment geo and aggs deprecated names (elastic#119872) (elastic#120287)

This adds comments to the deprecated names in geo and aggregations
explaining that we're not removing them so we don't break any callers.
Some of these have been deprecated for ten years but we're keeping them.

Author: nik9000

server/src/main/java/org/elasticsearch/index/query/GeoPolygonQueryBuilder.java

@@ -36,6 +36,8 @@
 import java.util.Objects;
 
 /**
+ * Deprecated geo query. Deprecated in #64227, 7.12/8.0. We do not plan to remove this so we
+ * do not break any users using this.
  * @deprecated use {@link GeoShapeQueryBuilder}
  */
 @Deprecated

server/src/main/java/org/elasticsearch/search/SearchModule.java

@@ -1180,6 +1180,10 @@ private void registerQueryParsers(List<SearchPlugin> plugins) {
         );
         registerQuery(
             new QuerySpec<>(
+                /*
+                 * Deprecated in #64227, 7.12/8.0. We do not plan to remove this so we
+                 * do not break any users using this.
+                 */
                 (new ParseField(GeoPolygonQueryBuilder.NAME).withAllDeprecated(GeoPolygonQueryBuilder.GEO_POLYGON_DEPRECATION_MSG)),
                 GeoPolygonQueryBuilder::new,
                 GeoPolygonQueryBuilder::fromXContent

server/src/main/java/org/elasticsearch/search/aggregations/bucket/range/GeoDistanceAggregationBuilder.java

@@ -48,6 +48,11 @@ public class GeoDistanceAggregationBuilder extends ValuesSourceAggregationBuilde
     public static final String NAME = "geo_distance";
     public static final ValuesSourceRegistry.RegistryKey<GeoDistanceAggregatorSupplier> REGISTRY_KEY =
         new ValuesSourceRegistry.RegistryKey<>(NAME, GeoDistanceAggregatorSupplier.class);
+    /**
+     * The point from which to measure the distance. This has many other names that have been
+     * deprecated since 2014, but we have no plans to remove these names so we don't break anyone
+     * using them.
+     */
     static final ParseField ORIGIN_FIELD = new ParseField("origin", "center", "point", "por");
     static final ParseField UNIT_FIELD = new ParseField("unit");
     static final ParseField DISTANCE_TYPE_FIELD = new ParseField("distance_type");

server/src/main/java/org/elasticsearch/search/aggregations/metrics/CardinalityAggregationBuilder.java

@@ -37,6 +37,12 @@ public final class CardinalityAggregationBuilder extends ValuesSourceAggregation
     public static final ValuesSourceRegistry.RegistryKey<CardinalityAggregatorSupplier> REGISTRY_KEY =
         new ValuesSourceRegistry.RegistryKey<>(NAME, CardinalityAggregatorSupplier.class);
 
+    /**
+     * Pre-2.0 rehashing was configurable, but it hasn't been for ~10 years. We always rehash because it's
+     * quite cheap. Attempting to enable or disable it is just a noop with a deprecation message. We have
+     * no plans to remove this parameter because it isn't worth breaking even the tiny fraction of users
+     * who are sending it. Deprecation was in #12931.
+     */
     private static final ParseField REHASH = new ParseField("rehash").withAllDeprecated("no replacement - values will always be rehashed");
     public static final ParseField PRECISION_THRESHOLD_FIELD = new ParseField("precision_threshold");
     public static final ParseField EXECUTION_HINT_FIELD_NAME = new ParseField("execution_hint");

server/src/main/java/org/elasticsearch/search/aggregations/metrics/PercentilesMethod.java

@@ -23,6 +23,10 @@
 public enum PercentilesMethod implements Writeable {
     /**
      * The TDigest method for calculating percentiles
+     * <p>
+     *     The {@code TDigest} and {@code TDIGEST} names have been deprecated since 8.0,
+     *     but we don't have any plans to remove it so we don't break anyone using it.
+     * </p>
      */
     TDIGEST("tdigest", "TDigest", "TDIGEST") {
         @Override
@@ -32,6 +36,10 @@ PercentilesConfig configFromStream(StreamInput in) throws IOException {
     },
     /**
      * The HDRHistogram method of calculating percentiles
+     * <p>
+     *     The {@code HDR} name has been deprecated since 8.0, but we don't have any plans
+     *     to remove it so we don't break anyone using it.
+     * </p>
      */
     HDR("hdr", "HDR") {
         @Override

server/src/main/java/org/elasticsearch/search/aggregations/support/ValueType.java

@@ -52,6 +52,11 @@ public enum ValueType implements Writeable {
     private final byte id;
     private final String preferredName;
 
+    /**
+     * Name of the {@code value_type} field in the JSON. The name {@code valueType} has
+     * been deprecated since before #22160, but we have no plans to remove it so we don't
+     * break anyone that might be using it.
+     */
     public static final ParseField VALUE_TYPE = new ParseField("value_type", "valueType");
 
     ValueType(byte id, String description, String preferredName, ValuesSourceType valuesSourceType, DocValueFormat defaultFormat) {

server/src/main/java/org/elasticsearch/search/sort/GeoDistanceSortBuilder.java

@@ -77,6 +77,11 @@ public class GeoDistanceSortBuilder extends SortBuilder<GeoDistanceSortBuilder>
     private static final ParseField UNIT_FIELD = new ParseField("unit");
     private static final ParseField DISTANCE_TYPE_FIELD = new ParseField("distance_type");
     private static final ParseField VALIDATION_METHOD_FIELD = new ParseField("validation_method");
+    /**
+     * Name for the sort {@link SortMode} which is mostly about sorting on multivalued fields.
+     * The {@code sort_mode} name has been deprecated since 5.0, but we don't plan to remove
+     * this so we don't break anyone using this.
+     */
     private static final ParseField SORTMODE_FIELD = new ParseField("mode", "sort_mode");
     private static final ParseField IGNORE_UNMAPPED = new ParseField("ignore_unmapped");