From 95ed98bca6847ee542ddeab60a05d73ee331939d Mon Sep 17 00:00:00 2001 From: Alexandre Mommers <919982+ygdrasil-io@users.noreply.github.com> Date: Wed, 30 Aug 2023 12:30:40 +0200 Subject: [PATCH 01/11] update: improve documentation on no-arg-plugin.md (#3754) * improve documentation on no-arg-plugin.md - Provide a sample annotation to illustrate how the plugin should be used. - Explain how to utilize the plugin using Kotlin DSL in Gradle, as an alternative for Groovy. * update: update no-arg-plugin.md updated wording applied code style --------- Co-authored-by: Andrey Polyakov --- docs/topics/no-arg-plugin.md | 46 +++++++++++++++++++++++++++++++++--- 1 file changed, 43 insertions(+), 3 deletions(-) diff --git a/docs/topics/no-arg-plugin.md b/docs/topics/no-arg-plugin.md index 8691bf43141..24ad11a5650 100644 --- a/docs/topics/no-arg-plugin.md +++ b/docs/topics/no-arg-plugin.md @@ -2,21 +2,46 @@ The *no-arg* compiler plugin generates an additional zero-argument constructor for classes with a specific annotation. -The generated constructor is synthetic so it can't be directly called from Java or Kotlin, but it can be called using reflection. +The generated constructor is synthetic, so it can't be directly called from Java or Kotlin, but it can be called using reflection. This allows the Java Persistence API (JPA) to instantiate a class although it doesn't have the zero-parameter constructor from Kotlin or Java point of view (see the description of `kotlin-jpa` plugin [below](#jpa-support)). +## In your Kotlin file + +Add new annotations to mark the code that needs a zero-argument constructor: + +```kotlin +package com.my + +annotation class Annotation +``` + ## Gradle Add the plugin using Gradle's plugins DSL: + + + +```kotlin +plugins { + kotlin("plugin.noarg") version "%kotlinVersion%" +} +``` + + + + ```groovy plugins { - id "org.jetbrains.kotlin.plugin.noarg" version "%kotlinVersion%" + id "org.jetbrains.kotlin.plugin.noarg" version "%kotlinVersion%" } ``` + + + Then specify the list of no-arg annotations that must lead to generating a no-arg constructor for the annotated classes: ```groovy @@ -74,12 +99,27 @@ and [`@MappedSuperclass`](https://docs.oracle.com/javaee/7/api/javax/persistence Add the plugin using the Gradle plugins DSL: + + + +```kotlin +plugins { + kotlin("plugin.jpa") version "%kotlinVersion%" +} +``` + + + + ```groovy plugins { - id "org.jetbrains.kotlin.plugin.jpa" version "%kotlinVersion%" + id "org.jetbrains.kotlin.plugin.jpa" version "%kotlinVersion%" } ``` + + + In Maven, enable the `jpa` plugin: ```xml From 03c749930c438f564ffe286127211e404d4c0403 Mon Sep 17 00:00:00 2001 From: Otso Virtanen Date: Wed, 30 Aug 2023 14:44:54 +0300 Subject: [PATCH 02/11] Update Realm link to point to Realm Kotlin SDK documentation (#3759) --- .../topics/multiplatform-mobile/multiplatform-mobile-samples.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/topics/multiplatform-mobile/multiplatform-mobile-samples.md b/docs/topics/multiplatform-mobile/multiplatform-mobile-samples.md index ed6f482ecbc..75a1b69bbe4 100644 --- a/docs/topics/multiplatform-mobile/multiplatform-mobile-samples.md +++ b/docs/topics/multiplatform-mobile/multiplatform-mobile-samples.md @@ -177,7 +177,7 @@ This is a curated list of cross-platform mobile projects created with Kotlin Mul - -
  • Uses Realm for data persistence
    • +
  • Uses Realm for data persistence
    • From f06296bba6eb572b5fd8b8ce8da9aaf84a7c8dff Mon Sep 17 00:00:00 2001 From: Danil Pavlov Date: Wed, 30 Aug 2023 15:30:40 +0200 Subject: [PATCH 03/11] update: android test naming in the new layout (#3762) * update: new android layout * Update to the latest Android SourceSet (#3743) --------- Co-authored-by: Qinglin --- .../multiplatform-mobile-understand-project-structure.md | 6 +++--- .../multiplatform/multiplatform-share-on-platforms.md | 2 +- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/topics/multiplatform-mobile/multiplatform-mobile-understand-project-structure.md b/docs/topics/multiplatform-mobile/multiplatform-mobile-understand-project-structure.md index 587795690ba..1b3cda4d5ab 100644 --- a/docs/topics/multiplatform-mobile/multiplatform-mobile-understand-project-structure.md +++ b/docs/topics/multiplatform-mobile/multiplatform-mobile-understand-project-structure.md @@ -159,7 +159,7 @@ Read [Multiplatform documentation on adding dependencies](multiplatform-add-depe Along with `*Main` source sets, there are three matching test source sets: * `commonTest` -* `androidTest` +* `androidUnitTest` * `iosTest` Use them to store unit tests for common and platform-specific source sets accordingly. @@ -178,7 +178,7 @@ kotlin { implementation(kotlin("test")) } } - val androidTest by getting + val androidUnitTest by getting val iosTest by getting } @@ -198,7 +198,7 @@ kotlin { implementation kotlin('test') } } - androidTest { + androidUnitTest { } iosTest { diff --git a/docs/topics/multiplatform/multiplatform-share-on-platforms.md b/docs/topics/multiplatform/multiplatform-share-on-platforms.md index ae1dd4ac83b..b17c62c05e8 100644 --- a/docs/topics/multiplatform/multiplatform-share-on-platforms.md +++ b/docs/topics/multiplatform/multiplatform-share-on-platforms.md @@ -19,7 +19,7 @@ just share it in the common source set. 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. -* Between the `main` and `test` source sets of a particular target, such as `androidMain` and `androidTest`. +* Between the `main` and `test` source sets of a particular target, such as `androidMain` and `androidUnitTest`. If you need to access platform-specific APIs from the shared code, use the Kotlin mechanism of [expected and actual declarations](multiplatform-connect-to-apis.md). From cd33fb0ae0c9caef79c1eac9b42d70485866f1ba Mon Sep 17 00:00:00 2001 From: Sarah Haggarty Date: Wed, 30 Aug 2023 15:46:30 +0200 Subject: [PATCH 04/11] update: add JVM bytecode 20 --- docs/topics/gradle/gradle-compiler-options.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/topics/gradle/gradle-compiler-options.md b/docs/topics/gradle/gradle-compiler-options.md index c890508ecb7..acb001588bc 100644 --- a/docs/topics/gradle/gradle-compiler-options.md +++ b/docs/topics/gradle/gradle-compiler-options.md @@ -171,7 +171,7 @@ Here is a complete list of options for Gradle tasks: | Name | Description | Possible values | Default value | |---------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------|-----------------------------| | `javaParameters` | Generate metadata for Java 1.8 reflection on method parameters | | false | -| `jvmTarget` | Target version of the generated JVM bytecode | "1.8", "9", "10", ..., "19". Also, see [Types for compiler options](#types-for-compiler-options) | "%defaultJvmTargetVersion%" | +| `jvmTarget` | Target version of the generated JVM bytecode | "1.8", "9", "10", ..., "20". Also, see [Types for compiler options](#types-for-compiler-options) | "%defaultJvmTargetVersion%" | | `noJdk` | Don't automatically include the Java runtime into the classpath | | false | | `jvmTargetValidationMode` |
  • Validation of the [JVM target compatibility](gradle-configure-project.md#check-for-jvm-target-compatibility-of-related-compile-tasks) between Kotlin and Java
  • A property for tasks of the `KotlinCompile` type.
    •  | `WARNING`, `ERROR`, `INFO` | `ERROR` | From 4f0058aae6033a75ddb034ea35f1283fc9ef944d Mon Sep 17 00:00:00 2001 From: Danil Pavlov Date: Fri, 1 Sep 2023 12:41:04 +0200 Subject: [PATCH 05/11] update: warnings for the new and the legacy memory manager pages (#3761) --- .../multiplatform-mobile-concurrency-and-coroutines.md | 4 +++- .../multiplatform-mobile-concurrency-overview.md | 4 +++- .../multiplatform-mobile-concurrent-mutability.md | 4 +++- docs/topics/native/native-immutability.md | 4 +++- docs/topics/native/native-ios-integration.md | 2 +- docs/topics/native/native-memory-manager.md | 4 ++-- 6 files changed, 15 insertions(+), 7 deletions(-) diff --git a/docs/topics/multiplatform-mobile/multiplatform-mobile-concurrency-and-coroutines.md b/docs/topics/multiplatform-mobile/multiplatform-mobile-concurrency-and-coroutines.md index a2c9dbe2911..e02d7f3c7d4 100644 --- a/docs/topics/multiplatform-mobile/multiplatform-mobile-concurrency-and-coroutines.md +++ b/docs/topics/multiplatform-mobile/multiplatform-mobile-concurrency-and-coroutines.md @@ -3,7 +3,9 @@ > This page describes the features of the legacy memory manager. Check out [Kotlin/Native memory management](native-memory-manager.md) > to learn about the new memory manager, which has been enabled by default since Kotlin 1.7.20. > -{type="note"} +> For more information on the concurrent programming in Kotlin, see the [Coroutines guide](coroutines-guide.md). +> +{type="warning"} When working with mobile platforms, you may need to write multithreaded code that runs in parallel. For this, you can use the [standard](#coroutines) `kotlinx.coroutines` library or its [multithreaded version](#multithreaded-coroutines) diff --git a/docs/topics/multiplatform-mobile/multiplatform-mobile-concurrency-overview.md b/docs/topics/multiplatform-mobile/multiplatform-mobile-concurrency-overview.md index c87abad4711..458f0d0df27 100644 --- a/docs/topics/multiplatform-mobile/multiplatform-mobile-concurrency-overview.md +++ b/docs/topics/multiplatform-mobile/multiplatform-mobile-concurrency-overview.md @@ -3,7 +3,9 @@ > This page describes the features of the legacy memory manager. Check out [Kotlin/Native memory management](native-memory-manager.md) > to learn about the new memory manager, which has been enabled by default since Kotlin 1.7.20. > -{type="note"} +> For more information on the concurrent programming in Kotlin, see the [Coroutines guide](coroutines-guide.md). +> +{type="warning"} When you extend your development experience from Android to Kotlin Multiplatform for mobile, you will encounter a different state and concurrency model for iOS. This is a Kotlin/Native model that compiles Kotlin code to native binaries that can run without a virtual machine, for example on iOS. diff --git a/docs/topics/multiplatform-mobile/multiplatform-mobile-concurrent-mutability.md b/docs/topics/multiplatform-mobile/multiplatform-mobile-concurrent-mutability.md index 53d9a9550cf..83917d6289d 100644 --- a/docs/topics/multiplatform-mobile/multiplatform-mobile-concurrent-mutability.md +++ b/docs/topics/multiplatform-mobile/multiplatform-mobile-concurrent-mutability.md @@ -3,7 +3,9 @@ > This page describes the features of the legacy memory manager. Check out [Kotlin/Native memory management](native-memory-manager.md) > to learn about the new memory manager, which has been enabled by default since Kotlin 1.7.20. > -{type="note"} +> For more information on the concurrent programming in Kotlin, see the [Coroutines guide](coroutines-guide.md). +> +{type="warning"} When it comes to working with iOS, [Kotlin/Native's state and concurrency model](multiplatform-mobile-concurrency-overview.md) has [two simple rules](multiplatform-mobile-concurrency-overview.md#rules-for-state-sharing). diff --git a/docs/topics/native/native-immutability.md b/docs/topics/native/native-immutability.md index 6d9920edfec..60e351cc1e9 100644 --- a/docs/topics/native/native-immutability.md +++ b/docs/topics/native/native-immutability.md @@ -3,7 +3,9 @@ > This page describes the features of the legacy memory manager. Check out [Kotlin/Native memory management](native-memory-manager.md) > to learn about the new memory manager, which has been enabled by default since Kotlin 1.7.20. > -{type="note"} +> For more information on the concurrent programming in Kotlin, see the [Coroutines guide](coroutines-guide.md). +> +{type="warning"} Kotlin/Native implements strict mutability checks, ensuring the important invariant that the object is either immutable or diff --git a/docs/topics/native/native-ios-integration.md b/docs/topics/native/native-ios-integration.md index 9f55d6e8c8c..73d177e0b3b 100644 --- a/docs/topics/native/native-ios-integration.md +++ b/docs/topics/native/native-ios-integration.md @@ -1,7 +1,7 @@ [//]: # (title: iOS integration) > This page describes the new memory manager enabled by default since Kotlin 1.7.20. See our [migration guide](native-migration-guide.md) -> to move your projects from the legacy memory manager. +> to move your projects from the legacy memory manager that will be removed in Kotlin 1.9.20. > {type="note"} diff --git a/docs/topics/native/native-memory-manager.md b/docs/topics/native/native-memory-manager.md index 4f3ddee07e2..9fc400fab37 100644 --- a/docs/topics/native/native-memory-manager.md +++ b/docs/topics/native/native-memory-manager.md @@ -1,7 +1,7 @@ [//]: # (title: Kotlin/Native memory management) -> This page describes features of the new memory manager enabled by default since Kotlin 1.7.20. -> See our [migration guide](native-migration-guide.md) to move your projects from the legacy memory manager. +> This page describes features of the new memory manager enabled by default since Kotlin 1.7.20. See our [migration guide](native-migration-guide.md) +> to move your projects from the legacy memory that will be removed in Kotlin 1.9.20. > {type="note"} From e06469f576d16de77a27d19249eb7dc6db628e7d Mon Sep 17 00:00:00 2001 From: Henok Woldesenbet <62161211+wldeh@users.noreply.github.com> Date: Fri, 1 Sep 2023 03:42:43 -0700 Subject: [PATCH 06/11] fix: correct typo in js-ir-compiler.md (#3765) --- docs/topics/js/js-ir-compiler.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/topics/js/js-ir-compiler.md b/docs/topics/js/js-ir-compiler.md index 36a342e3b1b..91f5eca383a 100644 --- a/docs/topics/js/js-ir-compiler.md +++ b/docs/topics/js/js-ir-compiler.md @@ -26,7 +26,7 @@ kotlin { * `LEGACY` uses the old compiler backend. * `BOTH` compiles your project with the new IR compiler as well as the default compiler backend. Use this mode for [authoring libraries compatible with both backends](#authoring-libraries-for-the-ir-compiler-with-backwards-compatibility). -> The old compiler backend has been deprecated since Kotlin 1.8.0. Starting with Kotlin 1.9.0, using compiler types `LEGACY` of `BOTH` leads to an error. +> The old compiler backend has been deprecated since Kotlin 1.8.0. Starting with Kotlin 1.9.0, using compiler types `LEGACY` or `BOTH` leads to an error. > {type="warning"} From 5cf39fbe6ff393b7b30d48140237d3b954849d02 Mon Sep 17 00:00:00 2001 From: Hossein zare <70435782+hosseinzare1@users.noreply.github.com> Date: Sun, 3 Sep 2023 09:17:12 +0330 Subject: [PATCH 07/11] Update gradle.md Page https://docs.gradle.org/current/userguide/getting_started.html is not available --- docs/topics/gradle/gradle.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/topics/gradle/gradle.md b/docs/topics/gradle/gradle.md index 5f3a5b2e755..6819a32162b 100644 --- a/docs/topics/gradle/gradle.md +++ b/docs/topics/gradle/gradle.md @@ -2,7 +2,7 @@ Gradle is a build system that helps to automate and manage your building process. It downloads required dependencies, packages your code, and prepares it for compilation. Learn about Gradle basics and specifics -on the [Gradle website](https://docs.gradle.org/current/userguide/getting_started.html). +on the [Gradle website](https://docs.gradle.org/current/userguide/userguide.html). You can set up your own project with [these instructions](gradle-configure-project.md) for different platforms or pass a small [step-by-step tutorial](get-started-with-jvm-gradle-project.md) that will show you how to create a simple backend From 22b3747ece0250814f4f87451e6f94a492099227 Mon Sep 17 00:00:00 2001 From: Sarah Haggarty Date: Wed, 6 Sep 2023 16:03:37 +0200 Subject: [PATCH 08/11] chore: clarify Int is default range for integer types --- docs/topics/numbers.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/topics/numbers.md b/docs/topics/numbers.md index 69797ce7e50..16b6c97686b 100644 --- a/docs/topics/numbers.md +++ b/docs/topics/numbers.md @@ -13,8 +13,8 @@ For integer numbers, there are four types with different sizes and, hence, value | `Long` | 64 |-9,223,372,036,854,775,808 (-263)|9,223,372,036,854,775,807 (263 - 1)| When you initialize a variable with no explicit type specification, the compiler automatically infers the type with the -smallest range enough to represent the value. If it is not exceeding the range of `Int`, the type is `Int`. If it exceeds, -the type is `Long`. To specify the `Long` value explicitly, append the suffix `L` to the value. +smallest range enough to represent the value starting from `Int`. If it is not exceeding the range of `Int`, the type is `Int`. +If it exceeds, the type is `Long`. To specify the `Long` value explicitly, append the suffix `L` to the value. Explicit type specification triggers the compiler to check the value not to exceed the range of the specified type. ```kotlin From 85d1d474670c0c164dd8c8b8ec7a6a11525a044f Mon Sep 17 00:00:00 2001 From: Sarah Haggarty Date: Wed, 6 Sep 2023 17:36:31 +0200 Subject: [PATCH 09/11] chore: clarify covariance example --- docs/topics/generics.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/topics/generics.md b/docs/topics/generics.md index 8a9c60ea22c..26cb463ba54 100644 --- a/docs/topics/generics.md +++ b/docs/topics/generics.md @@ -85,7 +85,7 @@ In other words, the wildcard with an _extends_\-bound (_upper_ bound) makes the The key to understanding why this works is rather simple: if you can only _take_ items from a collection, then using a collection of `String`s and reading `Object`s from it is fine. Conversely, if you can only _put_ items into the collection, it's okay to take a collection of `Object`s and put `String`s into it: in Java there is -`List`, a _supertype_ of `List`. +`List`, which accepts `String`s or any of its supertypes. The latter is called _contravariance_, and you can only call methods that take `String` as an argument on `List` (for example, you can call `add(String)` or `set(int, String)`). If you call something that returns `T` in `List`, From d8fcf8fc204fb27cfba8e98026c6c1be13714b77 Mon Sep 17 00:00:00 2001 From: Sebastian Aigner Date: Thu, 7 Sep 2023 14:28:22 +0200 Subject: [PATCH 10/11] Update link (#3772) --- .../topics/multiplatform-mobile/multiplatform-mobile-samples.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/topics/multiplatform-mobile/multiplatform-mobile-samples.md b/docs/topics/multiplatform-mobile/multiplatform-mobile-samples.md index 75a1b69bbe4..36a47596814 100644 --- a/docs/topics/multiplatform-mobile/multiplatform-mobile-samples.md +++ b/docs/topics/multiplatform-mobile/multiplatform-mobile-samples.md @@ -70,7 +70,7 @@ This is a curated list of cross-platform mobile projects created with Kotlin Mul - todoapp + TodoAppDecomposeMviKotlin Models, Networking, Presentation, Navigation and UI SQLDelight, Decompose, MVIKotlin, Reaktive Jetpack Compose, SwiftUI From 7096015a10e6723f14a5f576c75d94a258e26380 Mon Sep 17 00:00:00 2001 From: Henning Hoefer Date: Sat, 2 Sep 2023 19:42:15 +0200 Subject: [PATCH 11/11] Fix instructions to create a Kotlin worksheet Menu item in IDEA has been pushed to the "New Kotlin File" submenu. --- docs/topics/run-code-snippets.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/topics/run-code-snippets.md b/docs/topics/run-code-snippets.md index 3dcc97f9794..64498db522c 100644 --- a/docs/topics/run-code-snippets.md +++ b/docs/topics/run-code-snippets.md @@ -22,7 +22,7 @@ IntelliJ IDEA and Android Studio support Kotlin [scratch files and worksheets](h in a project, such as educational or demo materials. To create a Kotlin worksheet in a project directory, right-click the directory in the project tree and select - **New** | **Kotlin Worksheet**. + **New** | **Kotlin Class/File** | **Kotlin Worksheet**. Syntax highlighting, auto-completion, and other IntelliJ IDEA code editing features are supported in scratches and worksheets. There's no need to declare the `main()` function