From 09b14c567f3db521fdafafbee115404a8dcb4f04 Mon Sep 17 00:00:00 2001
From: Laurent Laborde <kerdezixe@gmail.com>
Date: Wed, 13 Sep 2023 11:48:41 +0200
Subject: [PATCH] fixing javadoc warnings

Signed-off-by: Laurent Laborde <kerdezixe@gmail.com>
---
 .../core/common/util/CollectionUtils.java     |  4 +-
 .../java/org/opensearch/geometry/Circle.java  | 66 +++++++++++++++++++
 2 files changed, 68 insertions(+), 2 deletions(-)

diff --git a/libs/core/src/main/java/org/opensearch/core/common/util/CollectionUtils.java b/libs/core/src/main/java/org/opensearch/core/common/util/CollectionUtils.java
index 2c7143ac14536..27869786b5deb 100644
--- a/libs/core/src/main/java/org/opensearch/core/common/util/CollectionUtils.java
+++ b/libs/core/src/main/java/org/opensearch/core/common/util/CollectionUtils.java
@@ -103,8 +103,8 @@ public static <T> List<T> rotate(final List<T> list, int distance) {
 
     /**
      * In place de-duplicates items in a list<p>
-     * Noop if the list is empty or has one item.<p>
-     *
+     * Noop if the list is empty or has one item.
+     * <p>
      * @throws NullPointerException if the list is `null` or comparator is `null`
      * @param array the list to de-duplicate
      * @param comparator the comparator to use to compare items
diff --git a/libs/geo/src/main/java/org/opensearch/geometry/Circle.java b/libs/geo/src/main/java/org/opensearch/geometry/Circle.java
index 6f8b0dc6929cc..cf1dce8966e1f 100644
--- a/libs/geo/src/main/java/org/opensearch/geometry/Circle.java
+++ b/libs/geo/src/main/java/org/opensearch/geometry/Circle.java
@@ -39,12 +39,19 @@
  * and optional altitude in meters.
  */
 public class Circle implements Geometry {
+
+    /** Empty circle : x=0, y=0, z=NaN radius=-1 */
     public static final Circle EMPTY = new Circle();
+    /** Latitude of the center of the circle in degrees */
     private final double y;
+    /** Longitude of the center of the circle in degrees */
     private final double x;
+    /** Altitude of the center of the circle in meters (NaN if irrelevant) */
     private final double z;
+    /** Radius of the circle in meters */
     private final double radiusMeters;
 
+    /** Create an {@link #EMPTY} circle */
     private Circle() {
         y = 0;
         x = 0;
@@ -52,10 +59,23 @@ private Circle() {
         radiusMeters = -1;
     }
 
+    /**
+     * Create a circle with no altitude.
+     * @param x Longitude of the center of the circle in degrees
+     * @param y Latitude of the center of the circle in degrees
+     * @param radiusMeters Radius of the circle in meters
+     */
     public Circle(final double x, final double y, final double radiusMeters) {
         this(x, y, Double.NaN, radiusMeters);
     }
 
+    /**
+     * Create a circle with altitude.
+     * @param x Longitude of the center of the circle in degrees
+     * @param y Latitude of the center of the circle in degrees
+     * @param z Altitude of the center of the circle in meters
+     * @param radiusMeters Radius of the circle in meters
+     */
     public Circle(final double x, final double y, final double z, final double radiusMeters) {
         this.y = y;
         this.x = x;
@@ -66,39 +86,68 @@ public Circle(final double x, final double y, final double z, final double radiu
         }
     }
 
+    /**
+     * @return The type of this geometry (always {@link ShapeType#CIRCLE})
+     */
     @Override
     public ShapeType type() {
         return ShapeType.CIRCLE;
     }
 
+    /**
+     * @return The y (latitude) of the center of the circle in degrees
+     */
     public double getY() {
         return y;
     }
 
+    /**
+     * @return The x (longitude) of the center of the circle in degrees
+     */
     public double getX() {
         return x;
     }
 
+    /**
+     * @return The radius of the circle in meters
+     */
     public double getRadiusMeters() {
         return radiusMeters;
     }
 
+    /**
+     * @return The altitude of the center of the circle in meters (NaN if irrelevant)
+     */
     public double getZ() {
         return z;
     }
 
+    /**
+     * @return The latitude (y) of the center of the circle in degrees
+     */
     public double getLat() {
         return y;
     }
 
+    /**
+     * @return The longitude (x) of the center of the circle in degrees
+     */
     public double getLon() {
         return x;
     }
 
+    /**
+     * @return The altitude (z) of the center of the circle in meters (NaN if irrelevant)
+     */
     public double getAlt() {
         return z;
     }
 
+    /**
+     * Compare this circle to another circle.
+     * @param o The other circle
+     * @return True if the two circles are equal in all their properties. False if null or different.
+     */
     @Override
     public boolean equals(Object o) {
         if (this == o) return true;
@@ -111,6 +160,9 @@ public boolean equals(Object o) {
         return (Double.compare(circle.z, z) == 0);
     }
 
+    /**
+     * @return The hashcode of this circle.
+     */
     @Override
     public int hashCode() {
         int result;
@@ -126,11 +178,22 @@ public int hashCode() {
         return result;
     }
 
+    /**
+     * Visit this circle with a {@link GeometryVisitor}.
+     * @param visitor The visitor
+     * @param <T> The return type of the visitor
+     * @param <E> The exception type of the visitor
+     * @return The result of the visitor
+     * @throws E The exception thrown by the visitor
+     */
     @Override
     public <T, E extends Exception> T visit(GeometryVisitor<T, E> visitor) throws E {
         return visitor.visit(this);
     }
 
+    /**
+     * @return True if this circle is empty (radius less than 0)
+     */
     @Override
     public boolean isEmpty() {
         return radiusMeters < 0;
@@ -141,6 +204,9 @@ public String toString() {
         return WellKnownText.INSTANCE.toWKT(this);
     }
 
+    /**
+     * @return True if this circle has an altitude. False if NaN.
+     */
     @Override
     public boolean hasZ() {
         return Double.isNaN(z) == false;