Merge branch 'master' into kaeawc/update-jvm-arg-docs

.teamcity/builds/kotlinlang/buidTypes/BuildReferenceDocs.kt

@@ -42,18 +42,6 @@ object BuildReferenceDocs : BuildType({
       dockerImage = "alpine"
       dockerImagePlatform = ScriptBuildStep.ImagePlatform.Linux
     }
-    script {
-      name = "Fix WRS-6159"
-      scriptContent = """
-            #!/usr/bin/env bash
-            ":" //# comment; exec /usr/bin/env node --input-type=module - "${'$'}@" < "${'$'}0"
-            
-            ${readScript("fix-wrs/index")}
-        """.trimIndent()
-      dockerImage = "node:22-slim"
-      dockerImagePlatform = ScriptBuildStep.ImagePlatform.Linux
-      dockerPull = true
-    }
   }
 
   dependencies {

docs/topics/coding-conventions.md

@@ -41,8 +41,8 @@ files in `org.example.kotlin.network.socket` should be in the `network/socket` s
 If a Kotlin file contains a single class or interface (potentially with related top-level declarations), its name should be the same
 as the name of the class, with the `.kt` extension appended. It applies to all types of classes and interfaces.
 If a file contains multiple classes, or only top-level declarations, choose a name describing what the file contains, and name the file accordingly.
-Use [an upper camel case](https://en.wikipedia.org/wiki/Camel_case) with an uppercase first letter (also known as Pascal case),
-for example, `ProcessDeclarations.kt`.
+Use [upper camel case](https://en.wikipedia.org/wiki/Camel_case), where the first letter of each word is capitalized.
+For example, `ProcessDeclarations.kt`.
 
 The name of the file should describe what the code in the file does. Therefore, you should avoid using meaningless
 words such as `Util` in file names.
@@ -81,7 +81,7 @@ have FQN `myPackage.PlatformKt`. This produces the "Duplicate JVM classes" error
 The simplest way to avoid that is renaming one of the files according to the guideline above. This naming scheme helps
 avoid clashes while retaining code readability.
 
-> There are two cases when these recommendations may seem redundant, but we still advise to follow them:
+> There are two scenarios where these recommendations may seem redundant, but we still advise to follow them:
 > 
 > * Non-JVM platforms don't have issues with duplicating file facades. However, this naming scheme can help you keep
 > file naming consistent.
@@ -135,9 +135,9 @@ Package and class naming rules in Kotlin are quite simple:
 
 * Names of packages are always lowercase and do not use underscores (`org.example.project`). Using multi-word
 names is generally discouraged, but if you do need to use multiple words, you can either just concatenate them together
-or use the camel case (`org.example.myProject`).
+or use camel case (`org.example.myProject`).
 
-* Names of classes and objects start with an uppercase letter and use the camel case:
+* Names of classes and objects use upper camel case:
 
 ```kotlin
 open class DeclarationProcessor { /*...*/ }
@@ -147,7 +147,7 @@ object EmptyDeclarationProcessor : DeclarationProcessor() { /*...*/ }
 
 ### Function names
 
-Names of functions, properties and local variables start with a lowercase letter and use the camel case and no underscores:
+Names of functions, properties and local variables start with a lowercase letter and use camel case with no underscores:
 
 ```kotlin
 fun processDeclarations() { /*...*/ }
@@ -181,8 +181,8 @@ class MyTestCase {
 ### Property names
 
 Names of constants (properties marked with `const`, or top-level or object `val` properties with no custom `get` function
-that hold deeply immutable data) should use uppercase underscore-separated ([screaming snake case](https://en.wikipedia.org/wiki/Snake_case))
-names:
+that hold deeply immutable data) should use all uppercase, underscore-separated names following the ([screaming snake case](https://en.wikipedia.org/wiki/Snake_case))
+convention:
 
 ```kotlin
 const val MAX_COUNT = 8
@@ -201,7 +201,7 @@ Names of properties holding references to singleton objects can use the same nam
 val PersonComparator: Comparator<Person> = /*...*/
 ```
 
-For enum constants, it's OK to use either uppercase underscore-separated names ([screaming snake case](https://en.wikipedia.org/wiki/Snake_case))
+For enum constants, it's OK to use either all uppercase, underscore-separated ([screaming snake case](https://en.wikipedia.org/wiki/Snake_case)) names
 (`enum class Color { RED, GREEN }`) or upper camel case names, depending on the usage. 
 
 ### Names for backing properties
@@ -257,11 +257,8 @@ if (elements != null) {
 ### Horizontal whitespace
 
 * Put spaces around binary operators (`a + b`). Exception: don't put spaces around the "range to" operator (`0..i`).
-
 * Do not put spaces around unary operators (`a++`).
-
 * Put spaces between control flow keywords (`if`, `when`, `for`, and `while`) and the corresponding opening parenthesis.
-
 * Do not put a space before an opening parenthesis in a primary constructor declaration, method declaration or method call.
 
 ```kotlin
@@ -274,28 +271,23 @@ fun bar() {
 }
 ```
 
-* Never put a space after `(`, `[`, or before `]`, `)`
-
-* Never put a space around `.` or `?.`: `foo.bar().filter { it > 2 }.joinToString()`, `foo?.bar()`
-
-* Put a space after `//`: `// This is a comment`
-
-* Do not put spaces around angle brackets used to specify type parameters: `class Map<K, V> { ... }`
-
-* Do not put spaces around `::`: `Foo::class`, `String::length`
-
-* Do not put a space before `?` used to mark a nullable type: `String?`
+* Never put a space after `(`, `[`, or before `]`, `)`.
+* Never put a space around `.` or `?.`: `foo.bar().filter { it > 2 }.joinToString()`, `foo?.bar()`.
+* Put a space after `//`: `// This is a comment`.
+* Do not put spaces around angle brackets used to specify type parameters: `class Map<K, V> { ... }`.
+* Do not put spaces around `::`: `Foo::class`, `String::length`.
+* Do not put a space before `?` used to mark a nullable type: `String?`.
 
 As a general rule, avoid horizontal alignment of any kind. Renaming an identifier to a name with a different length
 should not affect the formatting of either the declaration or any of the usages.
 
 ### Colon
 
-Put a space before `:` in the following cases:
+Put a space before `:` in the following scenarios:
 
-* when it's used to separate a type and a supertype
-* when delegating to a superclass constructor or a different constructor of the same class
-* after the `object` keyword
+* When it's used to separate a type and a supertype.
+* When delegating to a superclass constructor or a different constructor of the same class.
+* After the `object` keyword.
 
 Don't put a space before `:` when it separates a declaration and its type.
 
@@ -1062,14 +1054,14 @@ Learn the difference between [Java and Kotlin multiline strings](java-to-kotlin-
 
 ### Functions vs properties
 
-In some cases, functions with no arguments might be interchangeable with read-only properties. 
+In some scenarios, functions with no arguments might be interchangeable with read-only properties. 
 Although the semantics are similar, there are some stylistic conventions on when to prefer one to another.
 
 Prefer a property over a function when the underlying algorithm:
 
-* does not throw
-* is cheap to calculate (or cached on the first run)
-* returns the same result over invocations if the object state hasn't changed
+* Does not throw.
+* Is cheap to calculate (or cached on the first run).
+* Returns the same result over invocations if the object state hasn't changed.
 
 ### Extension functions
 
@@ -1137,10 +1129,10 @@ For the guidance on choosing the right scope function for your case, refer to [S
 
 When writing libraries, it's recommended to follow an additional set of rules to ensure API stability:
 
- * Always explicitly specify member visibility (to avoid accidentally exposing declarations as public API)
+ * Always explicitly specify member visibility (to avoid accidentally exposing declarations as public API).
  * Always explicitly specify function return types and property types (to avoid accidentally changing the return type
-   when the implementation changes)
+   when the implementation changes).
  * Provide [KDoc](kotlin-doc.md) comments for all public members, except for overrides that do not require any new documentation
-   (to support generating documentation for the library)
+   (to support generating documentation for the library).
 
 Learn more about best practices and ideas to consider when writing an API for your library in the [Library authors' guidelines](api-guidelines-introduction.md).

docs/topics/eap.md

@@ -57,4 +57,14 @@ check [our instructions on how to configure your build to support this version](
             <p>For more details, please refer to the <a href="https://github.com/JetBrains/kotlin/releases/tag/v2.1.0-Beta1">changelog</a> or <a href="whatsnew-eap.md">What's new in Kotlin 2.1.0-Beta1</a>.</p>
         </td>
     </tr>
+    <tr>
+        <td><strong>2.0.21-RC</strong>
+            <p>Released: <strong>October 1, 2024</strong></p>
+            <p><a href="https://github.com/JetBrains/kotlin/releases/tag/v2.0.21-RC" target="_blank">Release on GitHub</a></p>
+        </td>
+        <td>
+            <p>A bug fix release for Kotlin 2.0.20</p>
+            <p>For more details, please refer to the <a href="https://github.com/JetBrains/kotlin/releases/tag/v2.0.21-RC">changelog</a>.</p>
+        </td>
+    </tr>
 </table>

docs/topics/kotlin-doc.md

@@ -101,7 +101,7 @@ Specifies the version of the software in which the element being documented was
 Excludes the element from the generated documentation. Can be used for elements which are not part of the official
 API of a module but still have to be visible externally.
 
-> KDoc does not support the `@deprecated` tag. Instead, please use the `@Deprecated` annotation.
+> KDoc does not support the `@deprecated` tag. Instead, please use the [`@Deprecated`](https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-deprecated/) annotation.
 >
 {style="note"}
 

docs/topics/multiplatform/multiplatform-compatibility-guide.md

@@ -10,14 +10,14 @@ developing projects with Kotlin Multiplatform.
 
 ## Version compatibility
 
-When configuring your project, check the compatibility of a particular Kotlin version (the version of Kotlin Multiplatform Gradle plugin)
+When configuring your project, check the compatibility of a particular version of the Kotlin Multiplatform Gradle plugin (same as the Kotlin version in your project)
 with available Gradle, Xcode, and Android Gradle plugin versions:
 
-| Kotlin version | Gradle    | Android Gradle plugin | Xcode |
-|----------------|-----------|-----------------------|-------|
-| 2.0.20         | 7.5-8.8*  | 7.4.2–8.5             | 15.3  |
-| 2.0.0          | 7.5-8.5   | 7.4.2–8.3             | 15.3  |
-| 1.9.20         | 7.5-8.1.1 | 7.4.2–8.2             | 15.0  |
+| Kotlin Multiplatform plugin version | Gradle    | Android Gradle plugin | Xcode |
+|-------------------------------------|-----------|-----------------------|-------|
+| 2.0.20                              | 7.5-8.8*  | 7.4.2–8.5             | 15.3  |
+| 2.0.0                               | 7.5-8.5   | 7.4.2–8.3             | 15.3  |
+| 1.9.20                              | 7.5-8.1.1 | 7.4.2–8.2             | 15.0  |
 
 > Kotlin 2.0.20 is fully compatible with Gradle 6.8.3 through 8.6.
 > Gradle 8.7 and 8.8 are also supported, but you may see deprecation warnings in your multiplatform projects

docs/topics/multiplatform/multiplatform-configure-compilations.md

@@ -8,7 +8,7 @@ For each target, default compilations include:
 * `main` and `test` compilations for JVM, JS, and Native targets.
 * A [compilation](#compilation-for-android) per [Android build variant](https://developer.android.com/studio/build/build-variants), for Android targets.
 
-![Compilations](compilations.png)
+![Compilations](compilations.svg)
 
 If you need to compile something other than production code and unit tests, for example, integration or performance tests, 
 you can [create a custom compilation](#create-a-custom-compilation).
@@ -433,7 +433,7 @@ dependencies {
 
 Kotlin can build a [source set hierarchy](multiplatform-share-on-platforms.md#share-code-on-similar-platforms) with the `dependsOn` relation.
 
-![Source set hierarchy](jvm-js-main.png){width=400}
+![Source set hierarchy](jvm-js-main.svg)
 
 If the source set `jvmMain` depends on a source set `commonMain` then:
 

docs/topics/multiplatform/multiplatform-hierarchy.md

@@ -55,9 +55,9 @@ kotlin {
 When you declare the targets `androidTarget`, `iosArm64`, and `iosSimulatorArm64` in your code, the Kotlin Gradle plugin finds
 suitable shared source sets from the template and creates them for you. The resulting hierarchy looks like this:
 
-![An example of using the default hierarchy template](default-hierarchy-example.svg){thumbnail="true" width="350" thumbnail-same-file="true"}
+![An example of using the default hierarchy template](default-hierarchy-example.svg)
 
-Green source sets are actually created and present in the project, while gray ones from the default template are
+Colored source sets are actually created and present in the project, while gray ones from the default template are
 ignored. The Kotlin Gradle plugin hasn't created the `watchos` source set, for example, because there
 are no watchOS targets in the project.
 
@@ -316,7 +316,7 @@ kotlin {
 
 The resulting hierarchical structure will look like this:
 
-![Manually configured hierarchical structure](manual-hierarchical-structure.png)
+![Manually configured hierarchical structure](manual-hierarchical-structure.svg)
 
 You can have a shared source set for the following combinations of targets:
 

docs/topics/multiplatform/multiplatform-share-on-platforms.md

@@ -15,7 +15,7 @@ declarations](multiplatform-expect-actual.md).
 If you have business logic that is common for all platforms, you don't need to write the same code for each platform – 
 just share it in the common source set.
 
-![Code shared for all platforms](flat-structure.png)
+![Code shared for all platforms](flat-structure.svg)
 
 Some dependencies for source sets are set by default. You don't need to specify any `dependsOn` relations manually:
 * For all platform-specific source sets that depend on the common source set, such as `jvmMain`, `macosX64Main`, and others. 
@@ -53,7 +53,7 @@ the library which are available to the targets of each source set.
 
 For example, check out the following source set hierarchy from the `kotlinx.coroutines` repository:
 
-![Library hierarchical structure](lib-hierarchical-structure.png)
+![Library hierarchical structure](lib-hierarchical-structure.svg)
 
 The `concurrent` source set declares the function runBlocking and is compiled for the JVM and the native targets. 
 Once the `kotlinx.coroutines` library is updated and published with the hierarchical project structure, you can depend on 

docs/topics/native/apple-privacy-manifest.md

@@ -18,9 +18,9 @@ On this page, you'll find a detailed description of the problem and a recommenda
 
 ## What's the issue
 
-Apple requirements for App Store submissions are [changing in the spring of 2024](https://developer.apple.com/news/?id=r1henawx).
-You can already encounter warnings if you submit an app that doesn't specify a reason for using a required reason API in
-its privacy manifest. Starting May 1, 2024, [App Store Connect](https://appstoreconnect.apple.com) will not accept such apps at all.
+Apple's requirements for App Store submissions [have changed in the spring of 2024](https://developer.apple.com/news/?id=r1henawx).
+[App Store Connect](https://appstoreconnect.apple.com) no longer accepts apps that don't specify a reason for using a required
+reason API in their privacy manifests.
 
 This is an automatic check, not a manual moderation: your app's code is analyzed, and you receive a list of issues in an
 email. The email will reference the "ITMS-91053: Missing API declaration" issue, listing all API categories used in the

docs/topics/scripting/custom-script-deps-tutorial.md

@@ -1,6 +1,6 @@
 [//]: # (title: Get started with Kotlin custom scripting – tutorial)
 
-> Kotlin scripting is [Experimental](components-stability.md). It may be dropped or changed at any time.
+> Kotlin custom scripting is [Experimental](components-stability.md). It may be dropped or changed at any time.
 > Use it only for evaluation purposes. We appreciate your feedback on it in [YouTrack](https://kotl.in/issue).
 >
 {style="warning"}

docs/topics/whatsnew14.md

@@ -854,7 +854,7 @@ kotlin {
 For other combinations of targets, [create a hierarchy manually](multiplatform-hierarchy.md#manual-configuration)
 by connecting the source sets with the `dependsOn` relation.
 
-![Hierarchical structure](manual-hierarchical-structure.png)
+![Hierarchical structure](manual-hierarchical-structure.svg)
 
 <tabs group="build-script">
 <tab title="Kotlin" group-key="kotlin">

docs/topics/whatsnew1920.md

@@ -458,7 +458,7 @@ Green source sets are actually created and included in the project, while gray o
 
 To make it easier to work with the created project structure, IntelliJ IDEA now provides completion for source sets created with the default hierarchy template:
 
-<img src="multiplatform-hierarchy-completion.png" alt="IDE completion for source set names" width="350" animated="true"/>
+<img src="multiplatform-hierarchy-completion.animated.gif" alt="IDE completion for source set names" width="350" preview-src="multiplatform-hierarchy-completion.png"/>
 
 Kotlin also warns you if you attempt to access a source set that doesn't exist because you haven't declared the respective target.
 In the example below, there is no JVM target (only `androidTarget`, which is not the same). But let's try to use the `jvmMain` source set

docs/writerside.cfg

@@ -9,7 +9,7 @@
     <vars src="v.list"/>
     <settings>
         <default-property element-name="chapter" property-name="show-structure-depth" value="2"/>
-        <wrs-supernova use-version="242.21870"/>
+        <wrs-supernova use-version="2.1.1991-p6895"/>
     </settings>
     <instance id="help/kotlin-reference" src="kr.tree" web-path="/"/>
 </ihp>