docs!: overhaul for accuracy and quality

Author: wldeh

README.md

@@ -53,23 +53,15 @@ The `kotlinx-benchmark` library is designed to work with Kotlin/JVM, Kotlin/JS,
 <details open>
 <summary>Kotlin DSL</summary>
 
-1.  **Adding Dependency**: Add the `kotlinx-benchmark-runtime` dependency in your `build.gradle.kts` file.
-
-    ```kotlin
-    dependencies {
-        implementation("org.jetbrains.kotlinx:kotlinx-benchmark-runtime:0.4.8")
-    }
-    ```
-
-2.  **Applying Benchmark Plugin**: Next, apply the benchmark plugin.
+1.  **Applying Benchmark Plugin**: Apply the benchmark plugin.
 
     ```kotlin
     plugins {
-        id("org.jetbrains.kotlinx.benchmark") version "0.4.8"
+        id("org.jetbrains.kotlinx.benchmark") version "0.4.9"
     }
     ```
 
-3.  **Specifying Repository**: Ensure you have `mavenCentral()` for dependencies lookup in the list of repositories:
+2.  **Specifying Repository**: Ensure you have `mavenCentral()` for dependencies lookup in the list of repositories:
 
     ```kotlin
     repositories {
@@ -82,24 +74,16 @@ The `kotlinx-benchmark` library is designed to work with Kotlin/JVM, Kotlin/JS,
 <details>
 <summary>Groovy DSL</summary>
 
-1.  **Adding Dependency**: In your `build.gradle` file, include the `kotlinx-benchmark-runtime` dependency.
-
-    ```groovy
-    dependencies {
-        implementation 'org.jetbrains.kotlinx:kotlinx-benchmark-runtime:0.4.8'
-    }
-    ```
-
-2.  **Applying Benchmark Plugin**: Next, apply the benchmark plugin.
+1.  **Applying Benchmark Plugin**: Apply the benchmark plugin.
 
     ```groovy
     plugins {
         id 'org.jetbrains.kotlin.plugin.allopen' version "1.8.21"
-        id 'org.jetbrains.kotlinx.benchmark' version '0.4.8'
+        id 'org.jetbrains.kotlinx.benchmark' version '0.4.9'
     }
     ```
 
-3.  **Specifying Repository**: Ensure you have `mavenCentral()` in the list of repositories:
+2.  **Specifying Repository**: Ensure you have `mavenCentral()` in the list of repositories:
 
     ```groovy
     repositories {
@@ -163,42 +147,26 @@ This configuration ensures that your `MyBenchmark` class and its `benchmarkMetho
 
 You can alternatively mark your benchmark classes and methods `open` manually, but using the `allopen` plugin enhances code maintainability. For a practical example, please refer to [examples](examples/kotlin-kts).
 
-#### Java
-
- In order to conduct benchmarking in Java, you need to apply the Java plugin. 
-
-```kotlin
-plugins {
-    id("java")
-}
-```
-
-For a practical example, please refer to [examples](examples/java).
-
 #### Kotlin/JS
 
-For benchmarking Kotlin/JS code Node.js execution enviroment should be targeted. See https://kotlinlang.org/docs/js-project-setup.html#execution-environments. This is because kotlinx-benchmark-runtime uses Node.js environment to run benchmarks. Include the `nodejs()` method call in the `kotlin` block:
-
+Specify a compiler like the [IR compiler](https://kotlinlang.org/docs/js-ir-compiler.html) and set benchmarking targets in one step. Here, `jsIr` and `jsIrBuiltIn` are both using the IR compiler. The former uses benchmark.js, while the latter uses Kotlin's built-in plugin.
 
 ```kotlin
 kotlin {
-    js {
-        nodejs()
+    js('jsIr', IR) { 
+        nodejs() 
+    }
+    js('jsIrBuiltIn', IR) { 
+        nodejs() 
     }
 }
 ```
 
-For Kotlin/JS, only IR backend is supported. For more information on the IR compiler, please refer to the [Kotlin/JS IR compiler documentation](https://kotlinlang.org/docs/js-ir-compiler.html)
-
 #### Multiplatform
 
-For multiplatform projects, add the `kotlinx-benchmark-runtime` dependency to the `commonMain` source set, and be sure to apply the multiplatform plugin, as shown below:
+For multiplatform projects, add the `kotlinx-benchmark-runtime` dependency to the `commonMain` source set:
 
 ```kotlin
-plugins {
-    id("multiplatform")
-}
-
 kotlin {
     sourceSets {
         commonMain {

docs/benchmark-runtime.md

@@ -1,57 +1,28 @@
-# kotlinx.benchmark: A Comprehensive Guide to Benchmark Runtime for Each Target
+# Table of Contents
+1. [Introduction](#Understanding-Benchmark-Runtime-Across-Targets)
+2. [JVM: Harnessing JMH](#jvm-harnessing-jmh)
+3. [JavaScript: Benchmark.js Integration and In-built Support](#javascript-benchmarkjs-integration-and-in-built-support)
+4. [Native: Harnessing Native Capabilities](#native-harnessing-native-capabilities)
+5. [WebAssembly (Wasm): Custom-Built Benchmarking](#webassembly-wasm-custom-built-benchmarking)
 
-This document provides an in-depth overview of the kotlinx.benchmark library, focusing on how the benchmark runtime works for each supported target: JVM, JavaScript, and Native. This guide is designed for beginners and intermediates, providing a clear understanding of the underlying libraries used and the benchmark execution process.
+# Understanding Benchmark Runtime Across Targets
 
-## Table of Contents
+This comprehensive guide aims to shed light on the underlying libraries that Kotlinx Benchmark utilizes to measure performance on these platforms, and elucidate the benchmark runtime process.
 
-- [JVM Target](#jvm-target)
-- [JavaScript Target](#javascript-target)
-- [Native Target](#native-target)
+## JVM: Harnessing JMH
+In the JVM ecosystem, Kotlinx Benchmark capitalizes on the Java microbenchmarking harness [JMH](https://openjdk.org/projects/code-tools/jmh/). Designed by OpenJDK, JMH is a well-respected tool for creating, executing, and scrutinizing nano/micro/milli/macro benchmarks composed in Java and other JVM-compatible languages.
 
-## JVM Target
+Kotlinx Benchmark complements JMH with an array of advanced features that fine-tune JVM-specific settings. An exemplary feature is the handling of 'forks', a mechanism that facilitates running multiple tests in distinct JVM processes. By doing so, it assures a pristine environment for each test, enhancing the reliability of the benchmark results. Moreover, its sophisticated error and exception handling system ensures that any issues arising during testing are logged and addressed.
 
-The JVM target in kotlinx.benchmark leverages the Java Microbenchmark Harness (JMH) to run benchmarks. JMH is a widely-used tool for building, running, and analyzing benchmarks written in Java and other JVM languages.
+## JavaScript: Benchmark.js Integration and In-built Support
+Targeting JavaScript, Kotlinx Benchmark utilizes the `benchmark.js` library to measure performance. Catering to both synchronous and asynchronous benchmarks, this library enables evaluation of a vast array of JavaScript operations. `benchmark.js` operates by setting up a suite of benchmarks, where each benchmark corresponds to a distinct JavaScript operation to be evaluated. 
 
-### Benchmark Execution
+It's noteworthy that, alongside `benchmark.js`, Kotlinx Benchmark also incorporates its own built-in yet somewhat limited benchmarking system for Kotlin/JavaScript runtime.
 
-JMH handles the execution of benchmarks, managing the setup, running, and teardown of tests. It also handles the calculation of results, providing a robust and reliable framework for benchmarking on the JVM.
+## Native: Harnessing Native Capabilities
+For Native platforms, Kotlinx Benchmark resorts to its built-in benchmarking system, which is firmly rooted in platform-specific technologies. Benchmarks are defined in the form of suites, each representing a specific Kotlin/Native operation to be evaluated.
 
-### Benchmark Configuration
+## WebAssembly (Wasm): Custom-Built Benchmarking
+For Kotlin code running on WebAssembly (Wasm), Kotlinx Benchmark deploys built-in mechanisms to establish a testing milieu and measure code performance.
 
-The benchmark configuration is handled through annotations that map directly to JMH annotations. These include `@State`, `@Benchmark`, `@BenchmarkMode`, `@OutputTimeUnit`, `@Warmup`, `@Measurement`, and `@Param`.
-
-### File Operations
-
-File reading and writing operations are performed using standard Java I/O classes, providing a consistent and reliable method for file operations across all JVM platforms.
-
-## JavaScript Target
-
-The JavaScript target in kotlinx.benchmark leverages the Benchmark.js library to run benchmarks. Benchmark.js is a robust tool for executing JavaScript benchmarks in different environments, including browsers and Node.js.
-
-### Benchmark Execution
-
-Benchmark.js handles the execution of benchmarks, managing the setup, running, and teardown of tests. Just like JMH for JVM, it also handles the calculation of results, providing a reliable framework for benchmarking on JavaScript.
-
-### Benchmark Configuration
-
-The benchmark configuration in JavaScript is handled through a suite and benchmark API provided by benchmark.js. The API allows the users to specify the details of the benchmark such as the function to benchmark, setup function, and teardown function.
-
-### File Operations
-
-File reading and writing operations in JavaScript are performed using the standard JavaScript file I/O APIs. This includes the fs module in Node.js or the File API in browsers.
-
-## Native Target
-
-The Native target in kotlinx.benchmark leverages the built-in benchmarking capabilities of the Kotlin/Native runtime to execute benchmarks.
-
-### Benchmark Execution
-
-Kotlin/Native manages the execution of benchmarks, handling the setup, running, and teardown of tests. Just like JMH for JVM and Benchmark.js for JavaScript, Kotlin/Native also takes care of the calculation of results, providing a reliable framework for benchmarking in a native environment.
-
-### Benchmark Configuration
-
-The benchmark configuration in Kotlin/Native is handled through annotations that are similar to those used in the JVM target. These include `@State`, `@Benchmark`, `@BenchmarkMode`, `@OutputTimeUnit`, `@Warmup`, `@Measurement`, and `@Param`.
-
-### File Operations
-
-File operations in the Native target are handled through Kotlin's standard file I/O APIs. These APIs are compatible with all platforms supported by Kotlin/Native, providing a consistent method for file operations.
+In this setup, similarly a suite of benchmarks is created, each pinpointing a different code segment. The execution time of each benchmark is gauged using high-resolution JavaScript functions, thereby providing accurate and precise performance measurements.

docs/benchmarking-overview.md

@@ -131,4 +131,4 @@ While kotlinx-benchmark is geared towards microbenchmarking — typically examin
 
 If you'd like to dig deeper into the world of benchmarking, here are some resources to help you on your journey:
 
-- [Mastering High Performance with Kotlin](https://www.amazon.com/Mastering-High-Performance-Kotlin-difficulties/dp/178899664X)
+- [Mastering High Performance with Kotlin](https://www.amazon.com/Mastering-High-Performance-Kotlin-difficulties/dp/178899664X)

docs/compatibility.md

@@ -18,4 +18,4 @@ This guide provides you with information on the compatibility of different versi
 
 *Note: "Minimum Required" implies that any higher version than the one mentioned will also be compatible.*
 
-For more details about the changes, improvements, and updates in each `kotlinx-benchmark` version, please refer to the [RELEASE NOTES](https://github.com/Kotlin/kotlinx-benchmark/releases) and [CHANGELOG](../CHANGELOG.md).
+For more details about the changes, improvements, and updates in each `kotlinx-benchmark` version, please refer to the [RELEASE NOTES](https://github.com/Kotlin/kotlinx-benchmark/releases) and [CHANGELOG](../CHANGELOG.md).