Merge pull request #4576 from JetBrains/2-1-0-doc-update

feat: add Kotlin 2.1.0 release details

data/releases.yml

@@ -1,5 +1,5 @@
 url: https://github.com/JetBrains/kotlin/releases
 
 latest:
-  version: 2.0.21
-  url: https://github.com/JetBrains/kotlin/releases/tag/v2.0.21
+  version: 2.1.0
+  url: https://github.com/JetBrains/kotlin/releases/tag/v2.1.0

docs/kr.tree

@@ -23,10 +23,11 @@
 		<toc-element topic="competitive-programming.md"/>
 	</toc-element>
 	<toc-element toc-title="What's new in Kotlin">
-		<toc-element toc-title="Kotlin 2.0.20" accepts-web-file-names="whatsnew.html" topic="whatsnew2020.md"/>
-		<toc-element toc-title="Kotlin 2.0.0" topic="whatsnew20.md"/>
-		<toc-element toc-title="Kotlin 2.1.0-RC2" topic="whatsnew-eap.md"/>
+		<toc-element toc-title="Kotlin 2.1.0" accepts-web-file-names="whatsnew.html" topic="whatsnew21.md"/>
+		<toc-element toc-title="Kotlin 2.1.0-RC2" topic="whatsnew-eap.md" hidden="true"/>
 		<toc-element toc-title="Earlier versions">
+			<toc-element toc-title="Kotlin 2.0.20" topic="whatsnew2020.md"/>
+			<toc-element toc-title="Kotlin 2.0.0" topic="whatsnew20.md"/>
 			<toc-element toc-title="Kotlin 1.9.20" topic="whatsnew1920.md"/>
 			<toc-element toc-title="Kotlin 1.9.0" topic="whatsnew19.md"/>
 			<toc-element toc-title="Kotlin 1.8.20" topic="whatsnew1820.md"/>
@@ -119,9 +120,8 @@
 	</toc-element>
 	<toc-element toc-title="Multiplatform development">
 		<toc-element accepts-web-file-names="building-mpp-with-gradle.html,intro-to-kotlin-mpp.html,mpp-intro.html,mpp-get-started.html,multiplatform-tutorials.html,multiplatform-get-started.html" toc-title="Introduction" topic="multiplatform-intro.md"/>
-		<toc-element accepts-web-file-names="mpp-discover-project.html" toc-title="Understand basic project structure" topic="multiplatform-discover-project.md"/>
+		<toc-element accepts-web-file-names="mpp-discover-project.html,mpp-set-up-targets.html,multiplatform-set-up-targets.html" toc-title="Understand basic project structure" topic="multiplatform-discover-project.md"/>
 		<toc-element toc-title="Explore advanced project structure" topic="multiplatform-advanced-project-structure.md"/>
-		<toc-element toc-title="Set up targets" accepts-web-file-names="mpp-set-up-targets.html" topic="multiplatform-set-up-targets.md"/>
 		<toc-element toc-title="Share code">
 			<toc-element accepts-web-file-names="mpp-share-on-platforms.html" topic="multiplatform-share-on-platforms.md"/>
 			<toc-element topic="multiplatform-expect-actual.md"/>

docs/topics/coding-conventions.md

@@ -980,7 +980,7 @@ For example, use this syntax with `if`:
 if (x == null) ... else ...
 ```
 
-instead of this one with `when`:
+Instead of this one with `when`:
 
 ```kotlin
 when (x) {
@@ -991,6 +991,24 @@ when (x) {
 
 Prefer using `when` if there are three or more options.
 
+### Guard conditions in when expression
+
+Use parentheses when combining multiple boolean expressions in `when` expressions or statements with [guard conditions](control-flow.md#guard-conditions-in-when-expressions):
+
+```kotlin
+when (status) {
+    is Status.Ok if (status.info.isEmpty() || status.info.id == null) -> "no information"
+}
+```
+
+Instead of:
+
+```kotlin
+when (status) {
+    is Status.Ok if status.info.isEmpty() || status.info.id == null -> "no information"
+}
+```
+
 ### Nullable Boolean values in conditions
 
 If you need to use a nullable `Boolean` in a conditional statement, use `if (value == true)` or `if (value == false)` checks.

docs/topics/compiler-reference.md

@@ -54,6 +54,11 @@ Suppress the compiler from displaying warnings during compilation.
 
 Turn any warnings into a compilation error. 
 
+### -Wextra
+
+Enable [additional declaration, expression, and type compiler checks](whatsnew21.md#extra-compiler-checks) that
+emit warnings if true.
+
 ### -verbose
 
 Enable verbose logging output which includes details of the compilation process.
@@ -131,6 +136,14 @@ $ kotlinc @options/compiler.options hello.kt
 Enable usages of API that [requires opt-in](opt-in-requirements.md) with a requirement annotation with the given 
 fully qualified name.
 
+### -Xsuppress-warning
+
+Suppresses specific warnings [globally across the whole project](whatsnew-eap.md), for example:
+
+```bash
+kotlinc -Xsuppress-warning=NOTHING_TO_INLINE -Xsuppress-warning=NO_TAIL_CALLS_FOUND main.kt
+```
+
 ## Kotlin/JVM compiler options
 
 The Kotlin compiler for JVM compiles Kotlin source files into Java class files. 

docs/topics/compose-compiler-options.md

@@ -181,6 +181,10 @@ This results in fewer slots being used and fewer comparisons being made at runti
 
 ### OptimizeNonSkippingGroups
 
+> This feature is considered [Experimental](components-stability.md#stability-levels-explained).
+>
+{style="warning"}
+
 **Default**: disabled
 
 If enabled, remove groups around non-skipping composable functions.
@@ -190,10 +194,27 @@ unnecessary groups around composables which do not skip (and thus do not require
 This optimization will remove the groups, for example, around functions explicitly marked as `@NonSkippableComposable`
 and functions that are implicitly not skippable (inline functions and functions that return a non-`Unit` value such as `remember`).
 
-> This feature is considered [Experimental](components-stability.md#stability-levels-explained) and is disabled by default.
+### PausableComposition
+
+> This feature is considered [Experimental](components-stability.md#stability-levels-explained).
 >
 {style="warning"}
 
+**Default**: disabled
+
+If enabled, changes the code generation of composable functions to allow pausing when part of a pausable composition.
+This lets Compose runtime suspend composition at skipping points,
+splitting long-running compositions across multiple frames.
+
+Lazy lists and other performance intensive components use pausable composition to prefetch content
+that might cause visual jank when executed in a blocking manner.
+
+> The feature flag affects behavior only with a version of Compose runtime that supports pausable composition,
+> starting with `androidx.compose.runtime` 1.8.0-alpha02.
+> Older versions ignore the feature flag.
+>
+{style="note"}
+
 ### StrongSkipping
 
 **Default**: enabled

docs/topics/control-flow.md

@@ -260,6 +260,82 @@ fun Request.getBody() =
 
 The scope of a variable introduced as the subject is restricted to the body of the `when` expression or statement.
 
+### Guard conditions in when expressions
+
+> Guard conditions are an [experimental feature](components-stability.md#stability-levels-explained) that may be changed at any time.
+> We would appreciate your feedback in [YouTrack](https://youtrack.jetbrains.com/issue/KT-71140/Guard-conditions-in-when-expressions-feedback).
+>
+{style="warning"}
+
+Guard conditions allow you to include 
+more than one condition to the branches of a `when` expression, making complex control flow more explicit and concise.
+You can use guard conditions in `when` expressions or statements with a subject.
+
+To include a guard condition in a branch, place it after the primary condition, separated by `if`:
+
+```kotlin
+sealed interface Animal {
+    data class Cat(val mouseHunter: Boolean) : Animal
+    data class Dog(val breed: String) : Animal
+}
+
+fun feedAnimal(animal: Animal) {
+    when (animal) {
+        // Branch with only primary condition. Calls `feedDog()` when `Animal` is `Dog`
+        is Animal.Dog -> feedDog()
+        // Branch with both primary and guard conditions. Calls `feedCat()` when `Animal` is `Cat` and is not `mouseHunter`
+        is Animal.Cat if !animal.mouseHunter -> feedCat()
+        // Prints "Unknown animal" if none of the above conditions match
+        else -> println("Unknown animal")
+    }
+}
+```
+
+In a single `when` expression, you can combine branches with and without guard conditions. 
+The code in a branch with a guard condition runs only if both the primary condition and the guard condition evaluate to true.
+If the primary condition does not match, the guard condition is not evaluated. 
+
+If you use guard conditions in `when` statements without an `else` branch, and none of the conditions matches, none of the branches is executed. 
+
+Otherwise, if you use guard conditions in `when` expressions without an `else` branch, the compiler requires you to declare all the possible cases to avoid runtime errors.
+
+Additionally, guard conditions support `else if`:
+
+```kotlin
+when (animal) {
+    // Checks if `animal` is `Dog`
+    is Animal.Dog -> feedDog()
+    // Guard condition that checks if `animal` is `Cat` and not `mouseHunter`
+    is Animal.Cat if !animal.mouseHunter -> feedCat()
+    // Calls giveLettuce() if none of the above conditions match and animal.eatsPlants is true
+    else if animal.eatsPlants -> giveLettuce()
+    // Prints "Unknown animal" if none of the above conditions match
+    else -> println("Unknown animal")
+}
+```
+
+Combine multiple guard conditions within a single branch using the boolean operators `&&` (AND) or `||` (OR).
+Use parentheses around the boolean expressions to [avoid confusion](coding-conventions.md#guard-conditions-in-when-expression):
+
+```kotlin
+when (animal) {
+    is Animal.Cat if (!animal.mouseHunter && animal.hungry) -> feedCat()
+}
+```
+
+You can use guard conditions in any `when` expression or statement with a subject, except the case when you have multiple conditions separated by a comma.
+For example, `0, 1 -> print("x == 0 or x == 1")`.
+
+> To enable guard conditions in CLI, run the following command:
+>
+> `kotlinc -Xwhen-guards main.kt`
+>
+> To enable guard conditions in Gradle, add the following line to the `build.gradle.kts` file:
+>
+> `kotlin.compilerOptions.freeCompilerArgs.add("-Xwhen-guards")t`
+>
+{style="note"}
+
 ## For loops
 
 The `for` loop iterates through anything that provides an iterator. This is equivalent to the `foreach` loop in languages like C#.

docs/topics/eap.md

@@ -40,8 +40,9 @@ check [our instructions on how to configure your build to support this version](
 
 ## Build details
 
-<!--  _No preview versions are currently available._ --> 
+_No preview versions are currently available._ 
 
+<!--
 <table>
     <tr>
         <th>Build info</th>
@@ -58,3 +59,4 @@ check [our instructions on how to configure your build to support this version](
         </td>
     </tr>
 </table>
+-->

docs/topics/faq.md

@@ -102,7 +102,7 @@ When targeting native, Kotlin will produce platform-specific code (via LLVM).
 
 Kotlin lets you choose the version of JVM for execution. By default, the Kotlin/JVM compiler produces Java 8 compatible bytecode.
 If you want to make use of optimizations available in newer versions of Java, you can explicitly specify the target Java
-version from 9 to 21. Note that in this case the resulting bytecode might not run on lower versions.
+version from 9 to 23. Note that in this case the resulting bytecode might not run on lower versions.
 Starting with [Kotlin 1.5](whatsnew15.md#new-default-jvm-target-1-8), the compiler does not support producing bytecode compatible with Java versions below 8.
 
 ### Is Kotlin hard?

docs/topics/gradle/gradle-compilation-and-caches.md

@@ -13,11 +13,21 @@ On this page, you can learn about the following topics:
 
 ## Incremental compilation
 
-The Kotlin Gradle plugin supports incremental compilation. Incremental compilation tracks changes to files in the classpath
-between builds so that only the files affected by these changes are compiled. Incremental compilation works with [Gradle's
-build cache](#gradle-build-cache-support) and supports [compilation avoidance](https://docs.gradle.org/current/userguide/java_plugin.html#sec:java_compile_avoidance).
-
-Incremental compilation is supported for Kotlin/JVM and Kotlin/JS projects, and is enabled by default.
+The Kotlin Gradle plugin supports incremental compilation, which is enabled by default for Kotlin/JVM and Kotlin/JS projects.
+Incremental compilation tracks changes to files in the classpath between builds so that only the files affected
+by these changes are compiled.
+This approach works with [Gradle's build cache](#gradle-build-cache-support) and supports [compilation avoidance](https://docs.gradle.org/current/userguide/java_plugin.html#sec:java_compile_avoidance).
+
+For Kotlin/JVM, incremental compilation relies on classpath snapshots,
+which capture the API structure of modules to determine when recompilation is necessary.
+To optimize the overall pipeline, the Kotlin compiler uses two types of classpath snapshots:
+
+* **Fine-grained snapshots:** include detailed information about class members, such as properties or functions.
+When member-level changes are detected, the Kotlin compiler recompiles only the classes that depend on the modified members.
+To maintain performance, the Kotlin Gradle plugin creates coarse-grained snapshots for `.jar` files in the Gradle cache.
+* **Coarse-grained snapshots:** only contain the class [ABI](https://en.wikipedia.org/wiki/Application_binary_interface) hash.
+When a part of ABI changes, the Kotlin compiler recompiles all classes that depend on the changed class.
+This is useful for classes that change infrequently, such as external libraries.
 
 > Kotlin/JS projects use a different incremental compilation approach based on history files. 
 >
@@ -31,14 +41,14 @@ There are several ways to disable incremental compilation:
 
   The parameter should be added to each subsequent build.
 
-Note: Any build with incremental compilation disabled invalidates incremental caches. The first build is never incremental.
+When you disable incremental compilation, incremental caches become invalid after the build. The first build is never incremental.
 
 > Sometimes problems with incremental compilation become visible several rounds after the failure occurs. Use [build reports](#build-reports)
 > to track the history of changes and compilations. This can help you to provide reproducible bug reports.
 >
 {style="tip"}
 
-If you'd like to learn more about how our current incremental compilation approach works and compares to the previous one,
+To learn more about how our current incremental compilation approach works and compares to the previous one,
 see our [blog post](https://blog.jetbrains.com/kotlin/2022/07/a-new-approach-to-incremental-compilation-in-kotlin/).
 
 ### Precise backup of compilation tasks' outputs
@@ -307,7 +317,7 @@ From Kotlin 2.0.0, the K2 compiler is used by default.
 
 To use the previous compiler from Kotlin 2.0.0 onwards, either:
 
-* In your `build.gradle.kts` file, [set your language version](gradle-compiler-options.md#example-of-setting-a-languageversion) to `1.9`.
+* In your `build.gradle.kts` file, [set your language version](gradle-compiler-options.md#example-of-setting-languageversion) to `1.9`.
 
   OR
 * Use the following compiler option: `-language-version 1.9`.