AI-assisted javadoc and spotless

Author: JonasKunz

benchmarks/src/main/java/org/elasticsearch/benchmark/exponentialhistogram/ExponentialHistogramGenerationBench.java

@@ -43,7 +43,7 @@
 @State(Scope.Thread)
 public class ExponentialHistogramGenerationBench {
 
-    @Param({ "100", "500", "1000", "5000" , "10000", "20000"})
+    @Param({ "100", "500", "1000", "5000", "10000", "20000" })
     int bucketCount;
 
     @Param({ "NORMAL", "GAUSSIAN" })

libs/exponential-histogram/src/main/java/org/elasticsearch/exponentialhistogram/DownscaleStats.java

@@ -12,42 +12,52 @@
 import java.util.Arrays;
 
 /**
- * Data structure for effectively computing by how much the scale of a histogram needs to be reduced to reach a target bucket count.
- * This works by looking at each pair of neighboring buckets and checking at which scale reduction they would collapse to a single bucket.
+ * A data structure for efficiently computing the required scale reduction for a histogram to reach a target number of buckets.
+ * This works by examining pairs of neighboring buckets and determining at which scale reduction they would merge into a single bucket.
  */
 class DownscaleStats {
 
-    // collapsedBucketCount[i] represents the number of additional
+    // collapsedBucketCount[i] stores the number of additional
     // collapsed buckets when increasing the scale by (i+1) instead of just by (i)
     int[] collapsedBucketCount = new int[63];
 
+    /**
+     * Resets the data structure to its initial state.
+     */
     void reset() {
         Arrays.fill(collapsedBucketCount, 0);
     }
 
     void add(long previousBucketIndex, long currentBucketIndex) {
         if (currentBucketIndex <= previousBucketIndex) {
-            throw new IllegalArgumentException("currentBucketIndex must be bigger than previousBucketIndex");
+            throw new IllegalArgumentException("currentBucketIndex must be greater than previousBucketIndex");
         }
-        /* Below is an efficient variant of the following algorithm:
-        for (int i=0; i<63; i++) {
-            if (prevIndex>>(i+1) == currIndex>>(i+1)) {
-                collapsedBucketCount[i]++;
-                break;
-            }
-        }
-        So we find the smallest scale reduction required to make the two buckets collapse into one
-        */
+        /*
+         * Below is an efficient variant of the following algorithm:
+         * for (int i=0; i<63; i++) {
+         *     if (prevIndex>>(i+1) == currIndex>>(i+1)) {
+         *         collapsedBucketCount[i]++;
+         *         break;
+         *     }
+         * }
+         * So we find the smallest scale reduction required to make the two buckets collapse into one.
+         */
         long bitXor = previousBucketIndex ^ currentBucketIndex;
         int numEqualLeadingBits = Long.numberOfLeadingZeros(bitXor);
         if (numEqualLeadingBits == 0) {
-            // right-shifting will never make the buckets combine, because one is positive and the other negative
+            // right-shifting will never make the buckets combine, because one is positive and the other is negative
             return;
         }
         int requiredScaleChange = 64 - numEqualLeadingBits;
         collapsedBucketCount[requiredScaleChange - 1]++;
     }
 
+    /**
+     * Returns the number of buckets that will be merged after applying the given scale reduction.
+     *
+     * @param reduction the scale reduction factor
+     * @return the number of buckets that will be merged
+     */
     int getCollapsedBucketCountAfterScaleReduction(int reduction) {
         int totalCollapsed = 0;
         for (int i = 0; i < reduction; i++) {
@@ -56,6 +66,12 @@ int getCollapsedBucketCountAfterScaleReduction(int reduction) {
         return totalCollapsed;
     }
 
+    /**
+     * Returns the required scale reduction to reduce the number of buckets by at least the given amount.
+     *
+     * @param desiredCollapsedBucketCount the target number of buckets to collapse
+     * @return the required scale reduction
+     */
     int getRequiredScaleReductionToReduceBucketCountBy(int desiredCollapsedBucketCount) {
         if (desiredCollapsedBucketCount == 0) {
             return 0;
@@ -67,6 +83,6 @@ int getRequiredScaleReductionToReduceBucketCountBy(int desiredCollapsedBucketCou
                 return i + 1;
             }
         }
-        throw new IllegalArgumentException("it is not possible to reduce the bucket count by " + desiredCollapsedBucketCount);
+        throw new IllegalArgumentException("Cannot reduce the bucket count by " + desiredCollapsedBucketCount);
     }
 }

libs/exponential-histogram/src/main/java/org/elasticsearch/exponentialhistogram/ExponentialHistogram.java

@@ -12,128 +12,136 @@
 import java.util.OptionalLong;
 
 /**
- * Interface for implementations of exponential histograms adhering to the <a href="https://opentelemetry.io/docs/specs/otel/metrics/data-model/#exponentialhistogram">opentelemetry definition</a>.
- * This interface explicitly allows for sparse implementation: It does not offer to directly access buckets by index, instead it
- * is only possible to iterate over the buckets.<br>
+ * Interface for implementations of exponential histograms adhering to the
+ * <a href="https://opentelemetry.io/docs/specs/otel/metrics/data-model/#exponentialhistogram">OpenTelemetry definition</a>.
+ * This interface supports sparse implementations, allowing iteration over buckets without requiring direct index access.<br>
  * The most important properties are:
  * <ul>
- *     <li>The histogram has a scale parameter, which defines the accuracy. The <code>base</code> for the buckets is defined as <code>base = 2^(2^-scale)</code></li>
- *     <li>The histogram bucket at index <code>i</code> has the range <code>(base^i, base^(i+1)]</code> </li>
- *     <li>Negative values are represented by a separate negative range of buckets with the boundaries <code>(-base^(i+1), -base^i]</code></li>
- *     <li>histograms are perfectly subsetting: Increasing the scale by one exactly merges each pair of neighbouring buckets</li>
- *     <li>a special {@link ZeroBucket} is used to handle zero and close to zero values</li>
+ *     <li>The histogram has a scale parameter, which defines the accuracy.
+ *     The {@code base} for the buckets is defined as {@code base = 2^(2^-scale)}</li>
+ *     <li>The histogram bucket at index {@code i} has the range {@code (base^i, base^(i+1)]}</li>
+ *     <li>Negative values are represented by a separate negative range of buckets with the boundaries {@code (-base^(i+1), -base^i]}</li>
+ *     <li>Histograms are perfectly subsetting: increasing the scale by one merges each pair of neighboring buckets</li>
+ *     <li>A special {@link ZeroBucket} is used to handle zero and close-to-zero values</li>
  * </ul>
  *
  * <br>
- * In addition, in all algorithms we make a central assumption about the distribution of samples within each bucket:
- * We assume they all lie on the single point of least error relative to the bucket boundaries (see {@link ExponentialScaleUtils#getPointOfLeastRelativeError(long, int)}).
+ * Additionally, all algorithms assume that samples within a bucket are located at a single point: the point of least relative error
+ * (see {@link ExponentialScaleUtils#getPointOfLeastRelativeError(long, int)}).
  */
 public interface ExponentialHistogram {
 
-    //TODO: support min/max/sum/count storage and merging
-    //TODO: Add special positive and negative infinity buckets to allow representation of explicit bucket histograms with open boundaries
+    // TODO: support min/max/sum/count storage and merging
+    // TODO: Add special positive and negative infinity buckets to allow representation of explicit bucket histograms with open boundaries
 
-    // scale of 38 is the largest scale where at the borders we don't run into problems due to floating point precision when computing
-    // indices for double values
-    // Theoretically, a MAX_SCALE of 51 would work and would still cover the entire range of double values
-    // For that to work, we'll have to rework the math of converting from double to indices and back
+    // A scale of 38 is the largest scale where we don't run into problems at the borders due to floating-point precision when computing
+    // indices for double values.
+    // Theoretically, a MAX_SCALE of 51 would work and would still cover the entire range of double values.
+    // For that to work, the math for converting from double to indices and back would need to be reworked.
     // One option would be to use "Quadruple": https://github.com/m-vokhm/Quadruple
     int MAX_SCALE = 38;
 
-    // At this scale all double values already fall into a single bucket
+    // At this scale, all double values fall into a single bucket.
     int MIN_SCALE = -11;
 
-    // Only use 62 bit at max to allow to compute the difference between the smallest and largest index without causing overflow
-    // Also the extra bit gives us room for some tricks for compact storage
+    // Only use 62 bits at max to allow computing the difference between the smallest and largest index without causing an overflow.
+    // The extra bit also provides room for compact storage tricks.
     int MAX_INDEX_BITS = 62;
     long MAX_INDEX = (1L << MAX_INDEX_BITS) - 1;
     long MIN_INDEX = -MAX_INDEX;
 
     /**
-     * The scale of the histogram. Higher scales result in higher accuracy, but potentially higher bucket count.
+     * The scale of the histogram. Higher scales result in higher accuracy but potentially more buckets.
      * Must be less than or equal to {@link #MAX_SCALE} and greater than or equal to {@link #MIN_SCALE}.
+     *
+     * @return the scale of the histogram
      */
     int scale();
 
     /**
-     * @return the {@link ZeroBucket} representing the number of zero (or close to zero) values and its threshold
+     * @return the {@link ZeroBucket} representing the number of zero (or close-to-zero) values and its threshold
      */
     ZeroBucket zeroBucket();
 
     /**
-     * @return a {@link BucketIterator} for the populated, positive buckets of this histogram. {@link BucketIterator#scale()} of the return value must return the same value as {@link #scale()}.
+     * @return a {@link BucketIterator} for the populated, positive buckets of this histogram.
+     * The {@link BucketIterator#scale()} of the returned iterator must be the same as {@link #scale()}.
      */
     CopyableBucketIterator positiveBuckets();
 
     /**
-     * @return a {@link BucketIterator} for the populated, negative buckets of this histogram. {@link BucketIterator#scale()} of the return value must return the same value as {@link #scale()}.
+     * @return a {@link BucketIterator} for the populated, negative buckets of this histogram.
+     * The {@link BucketIterator#scale()} of the returned iterator must be the same as {@link #scale()}.
      */
     CopyableBucketIterator negativeBuckets();
 
     /**
      * Returns the highest populated bucket index, taking both negative and positive buckets into account.
-     * If there are neither positive nor negative buckets populated, an empty optional is returned.
+     *
+     * @return the highest populated bucket index, or an empty optional if no buckets are populated
      */
     OptionalLong maximumBucketIndex();
 
     /**
-     * Iterator over non-empty buckets of the histogram. Can represent either the positive or negative histogram range.
+     * An iterator over the non-empty buckets of the histogram for either the positive or negative range.
      *  <ul>
-     *      <li>The iterator always iterates from the lowest bucket index to the highest</li>
-     *      <li>The iterator never returns duplicate buckets (buckets with the same index) </li>
-     *      <li>The iterator never returns empty buckets ({@link #peekCount() is never zero}</li>
+     *      <li>The iterator always iterates from the lowest bucket index to the highest.</li>
+     *      <li>The iterator never returns duplicate buckets (buckets with the same index).</li>
+     *      <li>The iterator never returns empty buckets ({@link #peekCount()} is never zero).</li>
      *  </ul>
      */
     interface BucketIterator {
         /**
          * Checks if there are any buckets remaining to be visited by this iterator.
-         * If the end has been reached, it is illegal to call {@link #peekCount()}, {@link #peekIndex()} or {@link #advance()}.
+         * If the end has been reached, it is illegal to call {@link #peekCount()}, {@link #peekIndex()}, or {@link #advance()}.
          *
-         * @return <code>false</code>, if the end has been reached, <code>true</code> otherwise.
+         * @return {@code true} if the iterator has more elements, {@code false} otherwise
          */
         boolean hasNext();
 
         /**
-         * The number of items in the bucket this iterator currently points at. Does not advance the iterator by itself and therefore can be called repeatedly to return the same value.
-         * Must not be called if {@link #hasNext()} returns <code>false</code>.
+         * The number of items in the bucket at the current iterator position. Does not advance the iterator.
+         * Must not be called if {@link #hasNext()} returns {@code false}.
          *
          * @return the number of items in the bucket, always greater than zero
          */
         long peekCount();
 
         /**
-         * The index of the bucket this iterator currently points at. Does not advance the iterator by itself and therefore can be called repeatedly to return the same value.
-         * Must not be called if {@link #hasNext()} returns <code>false</code>.
+         * The index of the bucket at the current iterator position. Does not advance the iterator.
+         * Must not be called if {@link #hasNext()} returns {@code false}.
          *
          * @return the index of the bucket, guaranteed to be in the range [{@link #MIN_INDEX}, {@link #MAX_INDEX}]
          */
         long peekIndex();
 
         /**
          * Moves the iterator to the next, non-empty bucket.
-         * If {@link #hasNext()} is <code>true</code> after {@link #advance()}, {@link #peekIndex()} is guaranteed to return a value bigger than prior to the {@link #advance()} call.
+         * If {@link #hasNext()} is {@code true} after calling {@link #advance()}, {@link #peekIndex()} is guaranteed to return a value
+         * greater than the value returned prior to the {@link #advance()} call.
          */
         void advance();
 
         /**
          * Provides the scale that can be used to convert indices returned by {@link #peekIndex()} to the bucket boundaries,
-         * e.g. via {@link ExponentialScaleUtils#getLowerBucketBoundary(long, int)}.
+         * e.g., via {@link ExponentialScaleUtils#getLowerBucketBoundary(long, int)}.
          *
-         * @return the scale, which is guaranteed to be constant over the lifetime of this iterator.
+         * @return the scale, which is guaranteed to be constant over the lifetime of this iterator
          */
         int scale();
     }
 
     /**
-     * A {@link BucketIterator} which can be copied.
+     * A {@link BucketIterator} that can be copied.
      */
     interface CopyableBucketIterator extends BucketIterator {
 
         /**
-         * Provides a bucket iterator pointing at the same bucket of the same range of buckets as this iterator.
-         * Calling {@link #advance()} on the copied iterator does not affect <code>this</code> and vice-versa.
+         * Creates a copy of this bucket iterator, pointing at the same bucket of the same range of buckets.
+         * Calling {@link #advance()} on the copied iterator does not affect this instance and vice-versa.
+         *
+         * @return a copy of this iterator
          */
         CopyableBucketIterator copy();
     }
-
 }

libs/exponential-histogram/src/main/java/org/elasticsearch/exponentialhistogram/ExponentialHistogramGenerator.java

@@ -15,17 +15,17 @@
 import static org.elasticsearch.exponentialhistogram.ExponentialScaleUtils.computeIndex;
 
 /**
- * Class for accumulating raw values into an {@link ExponentialHistogram} with a given maximum bucket count.
+ * A class for accumulating raw values into an {@link ExponentialHistogram} with a given maximum number of buckets.
  *
- * If the number of values is less than or equal the bucket capacity, the resulting histogram is guaranteed
- * to represent the exact raw values with a relative error less than <code>2^(2^-MAX_SCALE) - 1</code>
+ * If the number of values is less than or equal to the bucket capacity, the resulting histogram is guaranteed
+ * to represent the exact raw values with a relative error less than {@code 2^(2^-MAX_SCALE) - 1}.
  */
 public class ExponentialHistogramGenerator {
 
-    // Merging individual values into a histogram would way to slow with our sparse, array-backed histogram representation
-    // Therefore for a bucket capacity of c, we first buffer c raw values to be inserted
-    // we then turn those into an "exact" histogram, which in turn we merge with our actual result accumulator
-    // This yields an amortized runtime of O( log(c) )
+    // Merging individual values into a histogram would be way too slow with our sparse, array-backed histogram representation.
+    // Therefore, for a bucket capacity of c, we first buffer c raw values to be inserted.
+    // We then turn those into an "exact" histogram, which in turn we merge with our actual result accumulator.
+    // This yields an amortized runtime of O(log(c)).
     private final double[] rawValueBuffer;
     int valueCount;
 
@@ -34,6 +34,11 @@ public class ExponentialHistogramGenerator {
 
     private boolean isFinished = false;
 
+    /**
+     * Creates a new instance with the specified maximum number of buckets.
+     *
+     * @param maxBucketCount the maximum number of buckets for the generated histogram
+     */
     public ExponentialHistogramGenerator(int maxBucketCount) {
         rawValueBuffer = new double[maxBucketCount];
         valueCount = 0;
@@ -42,8 +47,10 @@ public ExponentialHistogramGenerator(int maxBucketCount) {
     }
 
     /**
-     * Add the given value to the histogram.
-     * Must not be calles after {@link #get()} has been called.
+     * Adds the given value to the histogram.
+     * Must not be called after {@link #get()} has been called.
+     *
+     * @param value the value to add
      */
     public void add(double value) {
         if (isFinished) {
@@ -57,7 +64,9 @@ public void add(double value) {
     }
 
     /**
-     * @return the histogram representing the distribution of all accumulated values.
+     * Returns the histogram representing the distribution of all accumulated values.
+     *
+     * @return the histogram representing the distribution of all accumulated values
      */
     public ExponentialHistogram get() {
         isFinished = true;
@@ -66,17 +75,25 @@ public ExponentialHistogram get() {
     }
 
     /**
-     * Create a histogram representing the distribution of the given values.
+     * Creates a histogram representing the distribution of the given values.
      * The histogram will have a bucket count of at most the length of the provided array
-     * and will have a relative error less than <code>2^(2^-MAX_SCALE) - 1</code>.
+     * and will have a relative error less than {@code 2^(2^-MAX_SCALE) - 1}.
+     *
+     * @param values the values to be added to the histogram
+     * @return a new {@link ExponentialHistogram}
      */
     public static ExponentialHistogram createFor(double... values) {
         return createFor(values.length, Arrays.stream(values));
     }
+
     /**
-     * Create a histogram representing the distribution of the given values with at most the given number of buckets.
-     * If the given bucketCount is greater or equal to the number of values, the resulting histogram will have a
-     * relative error of less than <code>2^(2^-MAX_SCALE) - 1</code>.
+     * Creates a histogram representing the distribution of the given values with at most the given number of buckets.
+     * If the given bucketCount is greater than or equal to the number of values, the resulting histogram will have a
+     * relative error of less than {@code 2^(2^-MAX_SCALE) - 1}.
+     *
+     * @param bucketCount the maximum number of buckets
+     * @param values a stream of values to be added to the histogram
+     * @return a new {@link ExponentialHistogram}
      */
     public static ExponentialHistogram createFor(int bucketCount, DoubleStream values) {
         ExponentialHistogramGenerator generator = new ExponentialHistogramGenerator(bucketCount);