Comment benchmark methods

Author: Abduqodiri Qurbonzoda

benchmarks-mpp/src/jvmMain/kotlin/benchmarks/immutableList/Add.kt

@@ -26,11 +26,23 @@ open class Add {
     @Param(BM_1, BM_10, BM_100, BM_1000, BM_10000, BM_100000, BM_1000000, BM_10000000)
     var size: Int = 0
 
+    /**
+     * Adds [size] elements to an empty persistent list.
+     *
+     * Expected time: nearly constant.
+     * Expected memory: for size in 1..32 - O(size), nearly constant otherwise.
+     */
     @Benchmark
     fun addLast(): ImmutableList<String> {
         return persistentListAdd(size)
     }
 
+    /**
+     * Adds [size] elements to an empty persistent list and then iterates all elements from first to last.
+     *
+     * Expected time: [addLast] + [Iterate.firstToLast]
+     * Expected memory: [addLast] + [Iterate.firstToLast]
+     */
     @Benchmark
     fun addLastAndIterate(bh: Blackhole) {
         val list = persistentListAdd(size)
@@ -39,6 +51,12 @@ open class Add {
         }
     }
 
+    /**
+     * Adds [size] elements to an empty persistent list and then gets all elements by index from first to last.
+     *
+     * Expected time: [addLast] + [Get.getByIndex]
+     * Expected memory: [addLast] + [Get.getByIndex]
+     */
     @Benchmark
     fun addLastAndGet(bh: Blackhole) {
         val list = persistentListAdd(size)

benchmarks-mpp/src/jvmMain/kotlin/benchmarks/immutableList/Get.kt

@@ -34,6 +34,12 @@ open class Get {
         persistentList = persistentListAdd(size)
     }
 
+    /**
+     * Gets every element by index starting from first to last.
+     *
+     * Expected time: logarithmic
+     * Expected memory: none
+     */
     @Benchmark
     fun getByIndex(bh: Blackhole) {
         for (i in 0 until persistentList.size) {

benchmarks-mpp/src/jvmMain/kotlin/benchmarks/immutableList/Iterate.kt

@@ -34,13 +34,25 @@ open class Iterate {
         persistentList = persistentListAdd(size)
     }
 
+    /**
+     * Iterates every element starting from first to last.
+     *
+     * Expected time: nearly constant
+     * Expected memory: none once iterator created
+     */
     @Benchmark
     fun firstToLast(bh: Blackhole) {
         for (e in persistentList) {
             bh.consume(e)
         }
     }
 
+    /**
+     * Iterates every element starting from last to first.
+     *
+     * Expected time: nearly constant
+     * Expected memory: none once iterator created
+     */
     @Benchmark
     fun lastToFirst(bh: Blackhole) {
         val iterator = persistentList.listIterator(size)

benchmarks-mpp/src/jvmMain/kotlin/benchmarks/immutableList/Remove.kt

@@ -34,6 +34,12 @@ open class Remove {
         persistentList = persistentListAdd(size)
     }
 
+    /**
+     * Removes all elements by index starting from last to first.
+     *
+     * Expected time: nearly constant.
+     * Expected memory: for size in 1..32 - O(size), nearly constant otherwise.
+     */
     @Benchmark
     fun removeLast(): ImmutableList<String> {
         var list = persistentList

benchmarks-mpp/src/jvmMain/kotlin/benchmarks/immutableList/Set.kt

@@ -36,6 +36,12 @@ open class Set {
         randomIndices = List(size) { it }.shuffled()
     }
 
+    /**
+     * Updates each element by index starting from first to last.
+     *
+     * Expected time: logarithmic
+     * Expected memory: logarithmic
+     */
     @Benchmark
     fun setByIndex(): ImmutableList<String> {
         repeat(times = size) { index ->
@@ -44,6 +50,12 @@ open class Set {
         return persistentList
     }
 
+    /**
+     * Updates each element by index randomly.
+     *
+     * Expected time: logarithmic
+     * Expected memory: logarithmic
+     */
     @Benchmark
     fun setByRandomIndex(): ImmutableList<String> {
         repeat(times = size) { index ->

benchmarks-mpp/src/jvmMain/kotlin/benchmarks/immutableList/builder/Add.kt

@@ -29,11 +29,23 @@ open class Add {
     @Param(IP_100, IP_99_09, IP_95, IP_70, IP_50, IP_30, IP_0)
     var immutablePercentage: Double = 0.0
 
+    /**
+     * Adds [size] elements to an empty persistent list builder.
+     *
+     * Expected time: nearly constant.
+     * Expected memory: nearly constant.
+     */
     @Benchmark
     fun addLast(): PersistentList.Builder<String> {
         return persistentListBuilderAdd(size, immutablePercentage)
     }
 
+    /**
+     * Adds [size] elements to an empty persistent list builder and then iterates all elements from first to last.
+     *
+     * Expected time: [addLast] + [Iterate.firstToLast]
+     * Expected memory: [addLast] + [Iterate.firstToLast]
+     */
     @Benchmark
     fun addLastAndIterate(bh: Blackhole) {
         val builder = persistentListBuilderAdd(size, immutablePercentage)
@@ -42,6 +54,12 @@ open class Add {
         }
     }
 
+    /**
+     * Adds [size] elements to an empty persistent list builder and then gets all elements by index from first to last.
+     *
+     * Expected time: [addLast] + [Get.getByIndex]
+     * Expected memory: [addLast] + [Get.getByIndex]
+     */
     @Benchmark
     fun addLastAndGet(bh: Blackhole) {
         val builder = persistentListBuilderAdd(size, immutablePercentage)

benchmarks-mpp/src/jvmMain/kotlin/benchmarks/immutableList/builder/Get.kt

@@ -36,6 +36,12 @@ open class Get {
         builder = persistentListBuilderAdd(size, immutablePercentage)
     }
 
+    /**
+     * Gets every element by index starting from first to last.
+     *
+     * Expected time: logarithmic
+     * Expected memory: none
+     */
     @Benchmark
     fun getByIndex(bh: Blackhole) {
         for (i in 0 until builder.size) {

benchmarks-mpp/src/jvmMain/kotlin/benchmarks/immutableList/builder/Iterate.kt

@@ -36,13 +36,25 @@ open class Iterate {
         builder = persistentListBuilderAdd(size, immutablePercentage)
     }
 
+    /**
+     * Iterates every element starting from first to last.
+     *
+     * Expected time: nearly constant
+     * Expected memory: none once iterator created
+     */
     @Benchmark
     fun firstToLast(bh: Blackhole) {
         for (e in builder) {
             bh.consume(e)
         }
     }
 
+    /**
+     * Iterates every element starting from last to first.
+     *
+     * Expected time: nearly constant
+     * Expected memory: none once iterator created
+     */
     @Benchmark
     fun lastToFirst(bh: Blackhole) {
         val iterator = builder.listIterator(size)

benchmarks-mpp/src/jvmMain/kotlin/benchmarks/immutableList/builder/Remove.kt

@@ -28,6 +28,12 @@ open class Remove {
     @Param(IP_100, IP_99_09, IP_95, IP_70, IP_50, IP_30, IP_0)
     var immutablePercentage: Double = 0.0
 
+    /**
+     * Adds [size] elements to an empty persistent list builder and then removes each element by index starting from last to first.
+     *
+     * Expected time: [Add.addLast] + nearly constant.
+     * Expected memory: [Add.addLast] + nearly constant.
+     */
     @Benchmark
     fun addAndRemoveLast(): PersistentList.Builder<String> {
         val builder = persistentListBuilderAdd(size, immutablePercentage)

benchmarks-mpp/src/jvmMain/kotlin/benchmarks/immutableList/builder/Set.kt

@@ -38,6 +38,12 @@ open class Set {
         randomIndices = List(size) { it }.shuffled()
     }
 
+    /**
+     * Updates each element by index starting from first to last.
+     *
+     * Expected time: logarithmic
+     * Expected memory: nearly constant
+     */
     @Benchmark
     fun setByIndex(): PersistentList.Builder<String> {
         for (i in 0 until size) {
@@ -46,6 +52,12 @@ open class Set {
         return builder
     }
 
+    /**
+     * Updates each element by index randomly.
+     *
+     * Expected time: logarithmic
+     * Expected memory: nearly constant
+     */
     @Benchmark
     fun setByRandomIndex(): PersistentList.Builder<String> {
         for (i in 0 until size) {