📝 Add docstrings to pure

src/jmh/java/com/trivago/kangaroo/AbstractBenchHelper.java

@@ -9,6 +9,17 @@ public abstract class AbstractBenchHelper extends AbstractCommonBenchHelper {
     protected static final int NUM_VALUES = 1_000_000;
     protected ConcurrentLongLongMap map;
 
+    /**
+     * Initializes the concurrent map with a pre-populated set of random key-value pairs.
+     *
+     * <p>The map is configured with 16 buckets, an initial capacity defined by {@code NUM_VALUES},
+     * and a load factor of 0.8. When the {@code mode} parameter is {@code BUSY_WAITING}, the map is built
+     * with busy-waiting behavior; otherwise, a default configuration is used. After initialization,
+     * the map is populated with {@code NUM_VALUES} entries, each assigned random long keys and values
+     * generated via {@link ThreadLocalRandom}.</p>
+     *
+     * @param mode the map mode that determines whether busy-waiting is enabled
+     */
     public void initAndLoadData(PrimitiveMapBuilder.MapMode mode) {
         if (mode == PrimitiveMapBuilder.MapMode.BUSY_WAITING){
             map = ConcurrentLongLongMap.newBuilder()

src/jmh/java/com/trivago/kangaroo/AbstractCommonBenchHelper.java

@@ -9,6 +9,12 @@
 import java.util.concurrent.TimeUnit;
 
 public abstract class AbstractCommonBenchHelper {
+    /**
+     * Benchmarks the throughput of the "get" operation.
+     *
+     * <p>This method executes the testGet() operation using the throughput mode and measures its performance
+     * with 4 concurrent threads.
+     */
     @Threads(4)
     @Benchmark
     @BenchmarkMode(Mode.Throughput)
@@ -46,6 +52,13 @@ public void testRandomPutAvgTime() {
         testPut();
     }
 
+    /**
+     * Measures the average execution time of all operations.
+     * <p>
+     * Executes the {@code testAllOps()} method across four concurrent threads
+     * and reports the average execution time in nanoseconds.
+     * </p>
+     */
     @Threads(4)
     @Benchmark
     @BenchmarkMode(Mode.AverageTime)
@@ -54,9 +67,28 @@ public void testRandomAllOpsAvgTime() {
         testAllOps();
     }
 
-    public abstract void testGet();
+    /**
+ * Executes the GET operation benchmark.
+ *
+ * <p>This abstract method should be implemented by subclasses to perform the GET operation,
+ * which is used in benchmarking tests to measure performance metrics such as throughput and average execution time.</p>
+ */
+public abstract void testGet();
 
-    public abstract void testPut();
+    /**
+ * Executes a put operation for benchmarking purposes.
+ *
+ * <p>Implementations should override this method to define the logic for a put operation,
+ * which will be measured by throughput and average execution time benchmarks.</p>
+ */
+public abstract void testPut();
 
-    public abstract void testAllOps();
+    /**
+ * Executes a comprehensive set of benchmark operations.
+ *
+ * <p>This abstract method should be implemented to perform a mixed workload—typically combining
+ * get and put operations—to simulate a realistic full-spectrum scenario. It is invoked during
+ * benchmarking runs to measure both throughput and average execution time in multi-threaded environments.
+ */
+public abstract void testAllOps();
 }

src/jmh/java/com/trivago/kangaroo/FastutilWrapperBusyWaitingBenchmark.java

@@ -12,6 +12,12 @@
 @Warmup(iterations = 3, time = 1)
 @Measurement(iterations = 3, time = 2)
 public class FastutilWrapperBusyWaitingBenchmark extends AbstractBenchHelper {
+    /**
+     * Initializes and loads benchmark data using busy waiting mode.
+     *
+     * <p>This setup method is executed once per trial (as dictated by the @Setup(Level.Trial)
+     * annotation) to prepare the data required for the benchmark.
+     */
     @Setup(Level.Trial)
     public void loadData() {
         initAndLoadData(PrimitiveMapBuilder.MapMode.BUSY_WAITING);

src/jmh/java/com/trivago/kangaroo/FastutilWrapperDefaultBenchmark.java

@@ -12,6 +12,14 @@
 @Warmup(iterations = 3, time = 1)
 @Measurement(iterations = 3, time = 2)
 public class FastutilWrapperDefaultBenchmark extends AbstractBenchHelper {
+    /**
+     * Initializes and loads the data required for the benchmark trial in blocking mode.
+     *
+     * <p>
+     * This method is executed once before the benchmark trial starts and sets up the necessary data by
+     * invoking the initialization routine with the blocking mode specified by {@code PrimitiveMapBuilder.MapMode.BLOCKING}.
+     * </p>
+     */
     @Setup(Level.Trial)
     public void loadData() {
         initAndLoadData(PrimitiveMapBuilder.MapMode.BLOCKING);

src/jmh/java/com/trivago/kangaroo/JavaUtilWrapperBenchmark.java

@@ -21,6 +21,15 @@
 public class JavaUtilWrapperBenchmark extends AbstractCommonBenchHelper {
     Map<Long, Long> map;
 
+    /**
+     * Initializes the benchmark map with random long key-value pairs.
+     *
+     * <p>This setup method creates a {@code Long2LongOpenHashMap} with a predefined capacity and a load factor of 0.8,
+     * populates it with random long keys and values generated via {@code ThreadLocalRandom}, and then wraps the map with
+     * {@code Collections.synchronizedMap} to ensure thread-safe access during benchmark trials.
+     *
+     * <p>The method is executed once per trial, as indicated by the {@code @Setup(Level.Trial)} annotation.
+     */
     @Setup(Level.Trial)
     public void loadData() {
         Long2LongOpenHashMap m = new Long2LongOpenHashMap(AbstractBenchHelper.NUM_VALUES, 0.8f);
@@ -32,19 +41,44 @@ public void loadData() {
         map = Collections.synchronizedMap(m);
     }
 
+    /**
+     * Benchmarks a map retrieval operation using a randomly generated key.
+     *
+     * <p>This method generates a random key via {@link java.util.concurrent.ThreadLocalRandom}
+     * and retrieves the corresponding value from the synchronized map. It is designed to measure
+     * the performance of get operations during benchmarking tests.</p>
+     */
     @Override
 		public void testGet() {
         long key = ThreadLocalRandom.current().nextLong();
         map.get(key);
     }
 
+    /**
+     * Inserts a new entry into the map using randomly generated key and value.
+     *
+     * <p>This method generates random long values for both the key and value with 
+     * {@link ThreadLocalRandom} and inserts the entry into the synchronized map, 
+     * serving as a benchmark for put operations.</p>
+     */
     @Override
 		public void testPut() {
         long key = ThreadLocalRandom.current().nextLong();
         long value = ThreadLocalRandom.current().nextLong();
         map.put(key, value);
     }
 
+    /**
+     * Executes a randomly selected map operation for benchmarking purposes.
+     *
+     * <p>This method randomly performs one of three actions on the map:
+     * <ul>
+     *   <li>Inserts a new key-value pair (put operation) when the random choice equals 1.</li>
+     *   <li>Removes an entry (remove operation) when the random choice equals 2.</li>
+     *   <li>Retrieves a value (get operation) for any other random choice.</li>
+     * </ul>
+     * This supports mixed operation workloads during benchmark tests.
+     */
     @Override
 		public void testAllOps() {
         int op = ThreadLocalRandom.current().nextInt(3);

src/jmh/java/com/trivago/kangaroo/long2long/AbstractLongLongBenchHelper.java

@@ -10,6 +10,15 @@ public abstract class AbstractLongLongBenchHelper extends AbstractCommonBenchHel
     protected static final int NUM_VALUES = 1_000_000;
     protected ConcurrentLongLongMap map;
 
+    /**
+     * Initializes the concurrent map with a fixed configuration and populates it with random key-value pairs.
+     *
+     * <p>The map is built with 16 buckets, an initial capacity of {@code NUM_VALUES} (1,000,000), and a load factor of 0.8.
+     * The provided map mode is used during construction. After initialization, the map is filled with 
+     * {@code NUM_VALUES} randomly generated long key-value pairs.
+     *
+     * @param mode the map mode to be applied during the map's initialization
+     */
     public void initAndLoadData (PrimitiveMapBuilder.MapMode mode) {
         map = ConcurrentLongLongMap.newBuilder()
                 .withBuckets(16)
@@ -25,19 +34,41 @@ public void initAndLoadData (PrimitiveMapBuilder.MapMode mode) {
         }
     }
 
+    /**
+     * Retrieves a value from the concurrent map using a randomly generated key.
+     *
+     * <p>This benchmark method generates a random long key via ThreadLocalRandom and uses it to perform a
+     * get operation on the map, facilitating the measurement of concurrent retrieval performance.</p>
+     */
     @Override
 		public void testGet() {
         long key = ThreadLocalRandom.current().nextLong();
         map.get(key);
     }
 
+    /**
+     * Benchmarks the put operation on the concurrent map by inserting a randomly generated key-value pair.
+     *
+     * <p>This method uses thread-local random values for both the key and value to simulate a put operation
+     * in a concurrent benchmarking scenario.</p>
+     */
     @Override
 		public void testPut() {
         long key = ThreadLocalRandom.current().nextLong();
         long value = ThreadLocalRandom.current().nextLong();
         map.put(key, value);
     }
 
+    /**
+     * Executes a random operation on the concurrent map.
+     *
+     * <p>This method randomly selects one of three operations:
+     * <ul>
+     *   <li>When the random value is 1, it inserts a new key-value pair into the map.</li>
+     *   <li>When the random value is 2, it removes the entry associated with a random key.</li>
+     *   <li>Otherwise, it retrieves the value of a random key.</li>
+     * </ul>
+     */
     @Override
 		public void testAllOps() {
         int op = ThreadLocalRandom.current().nextInt(3);

src/jmh/java/com/trivago/kangaroo/long2long/FastutilWrapperBusyWaitingLongLongBenchmark.java

@@ -12,6 +12,12 @@
 @Warmup(iterations = 3, time = 1)
 @Measurement(iterations = 3, time = 2)
 public class FastutilWrapperBusyWaitingLongLongBenchmark extends AbstractLongLongBenchHelper {
+    /**
+     * Initializes and loads data in busy-waiting mode for the benchmark trial.
+     *
+     * <p>This method is executed once before the benchmark trial begins and sets up the data by
+     * invoking the superclass's data initialization routine with a busy-waiting strategy.
+     */
     @Setup(Level.Trial)
     public void loadData() {
         initAndLoadData(PrimitiveMapBuilder.MapMode.BUSY_WAITING);

src/jmh/java/com/trivago/kangaroo/long2long/FastutilWrapperDefaultLongLongBenchmark.java

@@ -12,6 +12,13 @@
 @Warmup(iterations = 3, time = 1)
 @Measurement(iterations = 3, time = 2)
 public class FastutilWrapperDefaultLongLongBenchmark extends AbstractLongLongBenchHelper {
+    /**
+     * Initializes and loads data for the benchmark trial.
+     * 
+     * <p>This setup method is executed once before the benchmark trial begins. It initializes
+     * the necessary data structures in blocking mode by invoking {@code initAndLoadData} with
+     * {@code PrimitiveMapBuilder.MapMode.BLOCKING}.</p>
+     */
     @Setup(Level.Trial)
     public void loadData() {
         initAndLoadData(PrimitiveMapBuilder.MapMode.BLOCKING);

src/jmh/java/com/trivago/kangaroo/long2long/JavaConcurrentLongLongBenchmark.java

@@ -19,6 +19,13 @@ public class JavaConcurrentLongLongBenchmark extends AbstractCommonBenchHelper {
 
     Map<Long, Long> map;
 
+    /**
+     * Initializes the concurrent map with random key-value pairs for the benchmarking trial.
+     *
+     * <p>This setup method, annotated with {@code @Setup(Level.Trial)}, creates a {@link java.util.concurrent.ConcurrentHashMap}
+     * using a predefined capacity and load factor, then populates it with entries where both keys and values are random long
+     * values generated by {@link java.util.concurrent.ThreadLocalRandom}.
+     */
     @Setup(Level.Trial)
     public void loadData() {
         map = new ConcurrentHashMap<>(AbstractLongLongBenchHelper.NUM_VALUES, 0.8f);
@@ -29,19 +36,44 @@ public void loadData() {
         }
     }
 
+    /**
+     * Benchmarks a get operation on the concurrent map by retrieving a value using a randomly generated key.
+     *
+     * <p>This method generates a random long key with ThreadLocalRandom and performs a lookup in the map,
+     * serving as part of the benchmarking process for concurrent retrieval performance.
+     */
     @Override
 		public void testGet() {
         long key = ThreadLocalRandom.current().nextLong();
         map.get(key);
     }
 
+    /**
+     * Inserts a random key-value pair into the map.
+     *
+     * <p>This method generates random long values for both the key and the value using ThreadLocalRandom,
+     * and inserts the generated pair into the map. It overrides the superclass method to simulate a put
+     * operation within a concurrent benchmarking environment.
+     */
     @Override
 		public void testPut() {
         long key = ThreadLocalRandom.current().nextLong();
         long value = ThreadLocalRandom.current().nextLong();
         map.put(key, value);
     }
 
+    /**
+     * Executes a randomly selected operation on the concurrent map.
+     *
+     * <p>This method simulates mixed access patterns by performing one of three operations:
+     * <ul>
+     *   <li>A put operation, inserting a new entry with random long key and value.</li>
+     *   <li>A remove operation, deleting an entry corresponding to a random long key.</li>
+     *   <li>A get operation, retrieving the value for a random long key.</li>
+     * </ul>
+     *
+     * <p>These operations are used for concurrent benchmarking of map performance.
+     */
     @Override
 		public void testAllOps() {
         int op = ThreadLocalRandom.current().nextInt(3);

src/jmh/java/com/trivago/kangaroo/long2long/JavaUtilWrapperLongLongBenchmark.java

@@ -20,6 +20,15 @@ public class JavaUtilWrapperLongLongBenchmark extends AbstractCommonBenchHelper
 
     Map<Long, Long> map;
 
+    /**
+     * Initializes the map with random long key-value pairs for benchmarking.
+     *
+     * <p>This method creates a Long2LongOpenHashMap with an initial capacity defined by
+     * AbstractLongLongBenchHelper.NUM_VALUES and a load factor of 0.8, populating it with
+     * randomly generated key-value pairs using ThreadLocalRandom. The generated map is then wrapped
+     * in a synchronized map to ensure thread safety during benchmark operations. This setup is
+     * executed once per trial as indicated by the @Setup(Level.Trial) annotation.</p>
+     */
     @Setup(Level.Trial)
     public void loadData() {
         Long2LongOpenHashMap m = new Long2LongOpenHashMap(AbstractLongLongBenchHelper.NUM_VALUES, 0.8f);
@@ -31,19 +40,43 @@ public void loadData() {
         map = Collections.synchronizedMap(m);
     }
 
+    /**
+     * Benchmarks the retrieval of a value from the map using a randomly generated key.
+     *
+     * <p>This method generates a random key and retrieves the associated value from the map, helping to simulate
+     * random access patterns during performance measurements.
+     */
     @Override
 		public void testGet() {
         long key = ThreadLocalRandom.current().nextLong();
         map.get(key);
     }
 
+    /**
+     * Inserts a random key-value pair into the map to benchmark the put operation.
+     *
+     * <p>This method generates random long values for both the key and the value using ThreadLocalRandom,
+     * then adds the pair to the map.
+     */
     @Override
 		public void testPut() {
         long key = ThreadLocalRandom.current().nextLong();
         long value = ThreadLocalRandom.current().nextLong();
         map.put(key, value);
     }
 
+    /**
+     * Performs a random operation on the map.
+     *
+     * <p>This method randomly selects one of the following operations using a randomly generated key:
+     * <ul>
+     *   <li>If the random operation equals 1, inserts a new key-value pair with a randomly generated value.</li>
+     *   <li>If the random operation equals 2, removes the entry associated with the key.</li>
+     *   <li>Otherwise, retrieves the value associated with the key.</li>
+     * </ul>
+     *
+     * <p>The method does not return any value.
+     */
     @Override
 		public void testAllOps() {
         int op = ThreadLocalRandom.current().nextInt(3);