fixup! Introduce docs/writing-benchmarks.md

Author: Abduqodiri Qurbonzoda

docs/writing-benchmarks.md

@@ -13,31 +13,34 @@ To get started, let's examine a simple example of a multiplatform benchmark:
 ```kotlin
 import kotlinx.benchmark.*
 
-@BenchmarkMode(Mode.Throughput)
-@OutputTimeUnit(TimeUnit.MILLISECONDS)
-@Warmup(iterations = 20, time = 1, timeUnit = TimeUnit.SECONDS)
-@Measurement(iterations = 20, time = 1, timeUnit = TimeUnit.SECONDS)
-@BenchmarkTimeUnit(TimeUnit.MILLISECONDS)
+@BenchmarkMode(Mode.AverageTime)
+@OutputTimeUnit(BenchmarkTimeUnit.MILLISECONDS)
+@Warmup(iterations = 10, time = 500, timeUnit = BenchmarkTimeUnit.MILLISECONDS)
+@Measurement(iterations = 20, time = 1, timeUnit = BenchmarkTimeUnit.SECONDS)
 @State(Scope.Benchmark)
 class ExampleBenchmark {
 
+    // Parameterizes the benchmark to run with different list sizes
     @Param("4", "10")
     var size: Int = 0
 
     private val list = ArrayList<Int>()
 
+    // Prepares the test environment before each benchmark run
     @Setup
     fun prepare() {
         for (i in 0..<size) {
             list.add(i)
         }
     }
 
+    // Cleans up resources after each benchmark run
     @TearDown
     fun cleanup() {
         list.clear()
     }
 
+    // The actual benchmark method
     @Benchmark
     fun benchmarkMethod(): Int {
         return list.sum()
@@ -55,29 +58,30 @@ The following annotations are available to define and fine-tune your benchmarks.
 
 ### @State
 
-The `@State` annotation is used to mark benchmark classes.
-In Kotlin/JVM, however, benchmark classes are not required to be annotated with `@State`.
+The `@State` annotation specifies the extent to which the state object is shared among the worker threads,
+and it is mandatory for benchmark classes to be marked with this annotation to define their scope of state sharing.
 
-In Kotlin/JVM, the annotation specifies the extent to which the state object is shared among the worker threads, e.g, `@State(Scope.Group)`.
+Currently, multi-threaded execution of a benchmark method is supported only on the JVM, where you can specify various scopes.
 Refer to [JMH documentation of Scope](https://javadoc.io/doc/org.openjdk.jmh/jmh-core/latest/org/openjdk/jmh/annotations/Scope.html)
-for details about available scopes. Multi-threaded execution of a benchmark method is not supported in other Kotlin targets,
-thus only `Scope.Benchmark` is available.
+for details about available scopes and their implications.
+In non-JVM targets, only `Scope.Benchmark` is applicable.
 
+When writing JVM-only benchmarks, benchmark classes are not required to be annotated with `@State`.
 Refer to [JMH documentation of @State](https://javadoc.io/doc/org.openjdk.jmh/jmh-core/latest/org/openjdk/jmh/annotations/State.html)
 for details about the effect and restrictions of the annotation in Kotlin/JVM.
 
-In our snippet, the `ExampleBenchmark` class is marked with `@State(Scope.Benchmark)`,
-indicating that the performance of benchmark methods in this class should be measured.
+In our snippet, the `ExampleBenchmark` class is annotated with `@State(Scope.Benchmark)`,
+indicating the state is shared across all worker threads.
 
 ### @Setup
 
-The `@Setup` annotation is used to mark a method that sets up the necessary preconditions for your benchmark test.
-It serves as a preparatory step where you set up the environment for the benchmark.
+The `@Setup` annotation marks a method that sets up the necessary preconditions for your benchmark test.
+It serves as a preparatory step where you initiate the benchmark environment.
 
-In Kotlin/JVM, you can specify when the setup method should be executed, e.g, `@Setup(Level.Iteration)`.
+The setup method is executed once before the entire set of iterations for a benchmark method begins.
+In Kotlin/JVM, you can specify when the setup method should be executed, e.g., `@Setup(Level.Iteration)`.
 Refer to [JMH documentation of Level](https://javadoc.io/doc/org.openjdk.jmh/jmh-core/latest/org/openjdk/jmh/annotations/Level.html)
-for details about available levels. In other targets, it operates always on the `Trial` level, meaning the setup method is
-executed once before the entire set of benchmark method iterations.
+for details about available levels in Kotlin/JVM.
 
 The key point to remember is that the `@Setup` method's execution time is not included in the final benchmark
 results - the timer starts only when the `@Benchmark` method begins. This makes `@Setup` an ideal place
@@ -90,28 +94,28 @@ In the provided example, the `@Setup` annotation is used to populate an `ArrayLi
 
 ### @TearDown
 
-The `@TearDown` annotation is used to denote a method that's executed after the benchmarking method(s).
-This method is typically responsible for cleaning up or deallocating any resources or conditions that were initialized in the `@Setup` method.
+The `@TearDown` annotation is used to denote a method that resets and cleans up the benchmarking environment.
+It is chiefly responsible for the cleanup or deallocation of resources and conditions set up in the `@Setup` method.
 
-In Kotlin/JVM, you can specify when the teardown method should be executed, e.g, `@TearDown(Level.Iteration)`.
+The teardown method is executed once after the entire iteration set of a benchmark method.
+In Kotlin/JVM, you can specify when the teardown method should be executed, e.g., `@TearDown(Level.Iteration)`.
 Refer to [JMH documentation of Level](https://javadoc.io/doc/org.openjdk.jmh/jmh-core/latest/org/openjdk/jmh/annotations/Level.html)
-for details about available levels. In other targets, it operates always on `Trial` level, meaning the teardown method
-is executed once after the entire set of benchmark method iterations.
+for details about available levels in Kotlin/JVM. 
 
-The `@TearDown` annotation helps you avoid performance bias and ensures the proper maintenance of resources and the
-preparation of a clean environment for the next run. As with the `@Setup` method, the `@TearDown` method's
-execution time is not included in the final benchmark results.
+The `@TearDown` annotation is crucial for avoiding performance bias, ensuring the proper maintenance of resources,
+and preparing a clean environment for the next run. Similar to the `@Setup` method, the execution time of the
+`@TearDown` method is not included in the final benchmark results.
 
 Refer to [JMH documentation of @TearDown](https://javadoc.io/doc/org.openjdk.jmh/jmh-core/latest/org/openjdk/jmh/annotations/TearDown.html)
-for details about the effect and restrictions of the annotation in Kotlin/JVM.
+for more information on the effect and restrictions of the annotation in Kotlin/JVM.
 
 In our example, the `cleanup` function annotated with `@TearDown` is used to clear our `ArrayList`.
 
 ### @Benchmark
 
 The `@Benchmark` annotation is used to specify the methods that you want to measure the performance of.
 It's the actual test you're running. The code you want to benchmark goes inside this method.
-All other annotations are used to control different things in measuring operations of benchmark methods.
+All other annotations are employed to configure the benchmark's environment and execution.
 
 Benchmark methods may include only a single [Blackhole](#blackhole) type as an argument, or have no arguments at all.
 It's important to note that in Kotlin/JVM benchmark methods must always be `public`.
@@ -126,30 +130,29 @@ which means the toolkit will measure the performance of the operation of summing
 The `@BenchmarkMode` annotation sets the mode of operation for the benchmark.
 
 Applying the `@BenchmarkMode` annotation requires specifying a mode from the `Mode` enum.
-In Kotlin/JVM, the `Mode` enum has several options, including `SingleShotTime`.
-
-Refer to [JMH documentation of Mode](https://javadoc.io/doc/org.openjdk.jmh/jmh-core/latest/org/openjdk/jmh/annotations/Mode.html)
-for details about available options. In other targets, only `Throughput` and `AverageTime` are available.
 `Mode.Throughput` measures the raw throughput of your code in terms of the number of operations it can perform per unit
 of time, such as operations per second. `Mode.AverageTime` is used when you're more interested in the average time it
 takes to execute an operation. Without an explicit `@BenchmarkMode` annotation, the toolkit defaults to `Mode.Throughput`.
+In Kotlin/JVM, the `Mode` enum has a few more options, including `SingleShotTime`.
+Refer to [JMH documentation of Mode](https://javadoc.io/doc/org.openjdk.jmh/jmh-core/latest/org/openjdk/jmh/annotations/Mode.html)
+for details about available options in Kotlin/JVM.
 
 The annotation is put at the enclosing class and has the effect over all `@Benchmark` methods in the class.
 In Kotlin/JVM, it may be put at `@Benchmark` method to have effect on that method only.
 Refer to [JMH documentation of @BenchmarkMode](https://javadoc.io/doc/org.openjdk.jmh/jmh-core/latest/org/openjdk/jmh/annotations/BenchmarkMode.html)
 for details about the effect of the annotation in Kotlin/JVM.
 
-In our example, `@BenchmarkMode(Mode.Throughput)` is used, meaning the benchmark focuses on the number of times the
-benchmark method can be executed per unit of time.
+In our example, `@BenchmarkMode(Mode.AverageTime)` is used, indicating that the benchmark aims to measure the
+average execution time of the benchmark method.
 
 ### @OutputTimeUnit
 
 The `@OutputTimeUnit` annotation specifies the time unit in which your results will be presented.
 This time unit can range from minutes to nanoseconds. If a piece of code executes within a few milliseconds,
-presenting the result in milliseconds or microseconds provides a more accurate and detailed measurement.
-Conversely, for operations with longer execution times, you might choose to display the output in microseconds, seconds, or even minutes.
+presenting the result in nanoseconds or microseconds provides a more accurate and detailed measurement.
+Conversely, for operations with longer execution times, you might choose to display the output in milliseconds, seconds, or even minutes.
 Essentially, the `@OutputTimeUnit` annotation enhances the readability and interpretability of benchmark results.
-If this annotation isn't specified, it defaults to using seconds as the time unit.
+By default, if the annotation is not specified, results are presented in seconds.
 
 The annotation is put at the enclosing class and has the effect over all `@Benchmark` methods in the class.
 In Kotlin/JVM, it may be put at `@Benchmark` method to have effect on that method only.
@@ -165,27 +168,27 @@ During this warmup phase, the code in your `@Benchmark` method is executed sever
 in the final benchmark results. The primary purpose of the warmup phase is to let the system "warm up" and reach its
 optimal performance state so that the results of measurement iterations are more stable.
 
-The annotation is put at the enclosing class and have the effect over all `@Benchmark` methods in the class.
+The annotation is put at the enclosing class and has the effect over all `@Benchmark` methods in the class.
 In Kotlin/JVM, it may be put at `@Benchmark` method to have effect on that method only.
 Refer to [JMH documentation of @Warmup](https://javadoc.io/doc/org.openjdk.jmh/jmh-core/latest/org/openjdk/jmh/annotations/Warmup.html)
 for details about the effect of the annotation in Kotlin/JVM.
 
-In our example, the `@Warmup` annotation is used to allow 20 iterations, each lasting one second,
-of executing the benchmark method before the actual measurement starts.
+In our example, the `@Warmup` annotation is used to allow 10 iterations of executing the benchmark method before
+the actual measurement starts. Each iteration lasts 500 milliseconds.
 
 ### @Measurement
 
 The `@Measurement` annotation controls the properties of the actual benchmarking phase.
 It sets how many iterations the benchmark method is run and how long each run should last.
 The results from these runs are recorded and reported as the final benchmark results.
 
-The annotation is put at the enclosing class and have the effect over all `@Benchmark` methods in the class.
+The annotation is put at the enclosing class and has the effect over all `@Benchmark` methods in the class.
 In Kotlin/JVM, it may be put at `@Benchmark` method to have effect on that method only.
 Refer to [JMH documentation of @Measurement](https://javadoc.io/doc/org.openjdk.jmh/jmh-core/latest/org/openjdk/jmh/annotations/Measurement.html)
 for details about the effect of the annotation in Kotlin/JVM.
 
-In our example, the `@Measurement` annotation specifies that the benchmark method will be run 20 iterations
-for a duration of one second for the final performance measurement.
+In our example, the `@Measurement` annotation specifies that the benchmark method will run 20 iterations,
+with each iteration lasting one second, for the final performance measurement.
 
 ### @Param
 
@@ -213,7 +216,7 @@ for available annotations.
 
 Modern compilers often eliminate computations they find unnecessary, which can distort benchmark results.
 In essence, `Blackhole` maintains the integrity of benchmarks by preventing unwanted optimizations such as dead-code
-elimination by the compiler or the runtime virtual machine. A `Blackhole` is used when the benchmark produces several values.
+elimination by the compiler or the runtime virtual machine. A `Blackhole` should be used when the benchmark produces several values.
 If the benchmark produces a single value, just return it. It will be implicitly consumed by a `Blackhole`.
 
 ### How to Use Blackhole:
@@ -232,5 +235,5 @@ fun iterateBenchmark(bh: Blackhole) {
 By consuming results, you signal to the compiler that these computations are significant and shouldn't be optimized away.
 
 For a deeper dive into `Blackhole` and its nuances in JVM, you can refer to:
-- [Official Javadocs](https://javadoc.io/static/org.openjdk.jmh/jmh-core/1.23/org/openjdk/jmh/infra/Blackhole.html)
+- [Official Javadocs](https://javadoc.io/doc/org.openjdk.jmh/jmh-core/latest/org/openjdk/jmh/infra/Blackhole.html)
 - [JMH](https://github.com/openjdk/jmh/blob/1.37/jmh-core/src/main/java/org/openjdk/jmh/infra/Blackhole.java#L157-L254)