docs!: overhaul for accuracy and quality

Author: Abduqodiri Qurbonzoda

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).

docs/interpreting-results.md

@@ -48,4 +48,4 @@ While analyzing benchmark results, watch out for these common pitfalls:
 
 4. **Dead Code Elimination:** The JVM is very good at optimizing your code, and sometimes it can optimize your benchmark right out of existence! Make sure your benchmarks do real work and that their results are used somehow (often by returning them from the benchmark method), or else the JVM might optimize them away.
 
-5. **Measurement error:** Ensure that you are not running any heavy processes in the background that could distort your benchmark results.
+5. **Measurement error:** Ensure that you are not running any heavy processes in the background that could distort your benchmark results.