Merge pull request #79 from Kotlin/develop

In preparation for kotlin-spec 1.5 release

Author: ice-phoenix

CONTRIBUTING.md

@@ -11,6 +11,8 @@ You have several options on how to contribute.
 1. Make a [pull request](https://github.com/Kotlin/kotlin-spec/pulls)
 1. Drop an email to [Marat Akhin](mailto:marat.akhin@jetbrains.com) or [Mikhail Belyaev](mailto:mikhail.belyaev@jetbrains.com)
 
+> Note: if doing a pull request, it should be based on the `develop` branch.
+
 In any of these cases, if we are talking about semantic changes to the specification, please try to include not only the improvements themselves, but also the reasoning on why you believe such a change is needed.
 
 > If we are talking about simple, but still very much appreciated improvements, e.g., fixing grammar, spelling or punctuation mistakes, no justification is required for those.

README.md

@@ -6,7 +6,7 @@
 
 This repository contains the specification of the [Kotlin programming language](https://kotlinlang.org), which describes how parts of the language should function *in more detail*, as compared to a more traditional user documentation on the [Kotlin Website](https://kotlinlang.org/docs/reference/).
 
-It would be most useful to those who are interested in how Kotlin works on a finer lever and how its features interoperate, e.g., language enthusiasts, compiler writers and Kotlin power-users.
+It would be most useful to those who are interested in how Kotlin works on a finer level and how its features interoperate, e.g., language enthusiasts, compiler writers and Kotlin power-users.
 However, if you are simply wondering, why some code you wrote works the way it does, this specification might help you get an answer to that.
 
 Currently, the specification covers only what we call *Kotlin/Core*: fundamental parts of Kotlin which should function the same way irregardless of the underlying platform.
@@ -67,6 +67,8 @@ You can help us make the Kotlin specification better by one of the following way
 1. Discuss the specification on the Kotlin [forums](https://discuss.kotlinlang.org/)
 1. Drop an email to [Marat Akhin](mailto:marat.akhin@jetbrains.com) or [Mikhail Belyaev](mailto:mikhail.belyaev@jetbrains.com) with your suggestions
 
+> Note: if doing a pull request, it should be based on the `develop` branch.
+
 We welcome any and all feedback to the specification, but may tweak, change or iterate with you on the contribution before including it in the specification.
 
 Further details on how to contribute to the specification are available in [CONTRIBUTING.md](CONTRIBUTING.md).

build.gradle.kts

@@ -1,3 +1,5 @@
+import at.phatbl.shellexec.ShellExec
+
 plugins {
     id("at.phatbl.shellexec") version "1.1.3"
 }
@@ -108,3 +110,8 @@ tasks.create<Delete>("clean") {
 
     delete("$projectDir/build")
 }
+
+tasks.create<ShellExec>("syncGrammarWithKotlinGrammarApache2Repo") {
+    group = "internal"
+    command = """echo -e Run the following command: git checkout release \&\& git subtree push --prefix grammar/src/main/antlr git@github.com:Kotlin/kotlin-grammar-apache2 release"""
+}

docs/build.gradle.kts

@@ -1,10 +1,11 @@
 import at.phatbl.shellexec.ShellExec
 import org.jetbrains.kotlin.gradle.tasks.KotlinCompile
 import java.nio.file.Paths
+import java.net.URI
 
 plugins {
     application
-    id("kotlin") version "1.3.41"
+    id("kotlin") version "1.4.31"
     id("at.phatbl.shellexec")
 }
 
@@ -26,10 +27,10 @@ fun getScriptText(scriptName: String): String {
 
     val res = with(StringBuilder()) {
         append("PROJECT_DIR=$projectDir$ls")
-        if(disableTODOS) append("TODO_OPTION=--disable-todos$ls")
+        if (disableTODOS) append("TODO_OPTION=--disable-todos$ls")
         else append("TODO_OPTION=--enable-todos$ls")
 
-        if(enableStaticMath) append("STATIC_MATH_OPTION=--enable-static-math$ls")
+        if (enableStaticMath) append("STATIC_MATH_OPTION=--enable-static-math$ls")
         else append("STATIC_MATH_OPTION=--disable-static-math$ls")
 
         append(buildTemplate)
@@ -39,23 +40,32 @@ fun getScriptText(scriptName: String): String {
 }
 
 repositories {
-    maven { setUrl("https://dl.bintray.com/vorpal-research/kotlin-maven") }
+    maven {
+        url = URI("https://maven.pkg.github.com/vorpal-research/kotlin-maven")
+        credentials {
+            username = "vorpal-reseacher"
+            password = "\u0031\u0030\u0062\u0037\u0064\u0066\u0031\u0032\u0063\u0064" +
+                    "\u0035\u0034\u0038\u0037\u0034\u0065\u0030\u0034\u0035\u0035" +
+                    "\u0038\u0031\u0063\u0039\u0039\u0062\u0031\u0066\u0032\u0030" +
+                    "\u0038\u0065\u0031\u0061\u0035\u0033\u0065\u0036\u0032\u0038"
+        }
+    }
     mavenCentral()
 }
 
-java.sourceSets {
-    "main" {
+sourceSets {
+    main {
         java.srcDir("src/main/kotlin")
     }
 }
 
 dependencies {
-    compile("ru.spbstu:g4toEBNF:0.0.0.3")
-    compile("ru.spbstu:kotlin-pandoc:0.0.10")
-    compile("ru.spbstu:simple-diagrammer:0.0.0.6")
-    compile("com.github.ajalt:clikt:1.7.0")
-    compile("com.zaxxer:nuprocess:2.0.1")
-    compile("org.antlr:antlr4:4.+")
+    implementation("ru.spbstu:g4-to-ebnf:0.0.0.4")
+    implementation("ru.spbstu:kotlin-pandoc:0.0.13")
+    implementation("ru.spbstu:simple-diagrammer:0.0.0.7")
+    implementation("com.github.ajalt:clikt:1.7.0")
+    implementation("com.zaxxer:nuprocess:2.0.1")
+    implementation("org.antlr:antlr4:4.+")
 }
 
 tasks.withType<KotlinCompile> {
@@ -96,7 +106,7 @@ tasks.create<JavaExec>("convertGrammar") {
 
     outputs.file(outputFile)
 
-    classpath = java.sourceSets["main"].runtimeClasspath
+    classpath = sourceSets["main"].runtimeClasspath
     main = "org.jetbrains.kotlin.spec.ConvertGrammarKt"
     args = listOf("-d", grammarsDir, "-l", lexerGrammar, "-p", parserGrammar, "-o", outputFile)
 }
@@ -130,7 +140,7 @@ tasks.create<ShellExec>("buildHtmlBySections") {
 tasks.create<JavaExec>("execute") {
     group = "internal"
 
-    classpath = java.sourceSets["main"].runtimeClasspath
+    classpath = sourceSets["main"].runtimeClasspath
 
     main = project.findProperty("mainClass") as? String ?: ""
     args = (project.findProperty("args") as? String)?.split(" ") ?: emptyList()

docs/scripts/build/buildHtml.sh

@@ -112,3 +112,5 @@
 
 \opMathIT{\Assigned}{Assigned}
 \opMathIT{\Unassigned}{Unassigned}
+
+\newcommand{\coroutineSuspended}{\texttt{CO\-RO\-U\-TINE\-\_SUS\-PEN\-DED}}

docs/scripts/build/buildHtmlBySections.sh

@@ -112,9 +112,15 @@ Annotations may be declared *repeatable* (meaning that the same annotation may b
   `kotlin.annotation.Repeatable` is an annotation which is only used on annotation classes to specify whether this particular annotation is repeatable.
   Annotations are non-repeatable by default.
 
-* `kotlin.Experimental` / `kotlin.UseExperimental`
+* `kotlin.RequiresOptIn` / `kotlin.OptIn`
 
-  `kotlin.Experimental` is an annotation class with a single field:
+  `kotlin.RequiresOptIn` is an annotation class with two fields:
+
+  * ```kotlin
+    val message: String = ""
+    ```
+
+    The message describing the particular opt-in requirements.
 
   * ```kotlin
     val level: Level = Level.ERROR
@@ -124,17 +130,19 @@ Annotations may be declared *repeatable* (meaning that the same annotation may b
 
   This annotation is used to introduce implementation-defined experimental language or standard library features.
 
-  `kotlin.UseExperimental` is an annotation class with a single field:
+  `kotlin.OptIn` is an annotation class with a single field:
 
   * ```kotlin
     vararg val markerClass: KClass<out Annotation>
     ```
 
     The classes which this annotation allows to use.
 
-  This annotation is used to explicitly mark declarations which use experimental features marked by `kotlin.Experimental`.
+  This annotation is used to explicitly mark declarations which use experimental features marked by `kotlin.RequiresOptIn`.
 
   It is implementation-defined how this annotation is processed.
+  
+  > Note: before Kotlin 1.4.0, there were two other built-in annotations: `@Experimental` (now replaced by `@RequiresOptIn`) and `@UseExperimental` (now replaced by `@OptIn`) serving the same purpose which are now deprecated.
 
   TODO(Experimental status is still experimental itself)
 
@@ -226,3 +234,19 @@ Annotations may be declared *repeatable* (meaning that the same annotation may b
   `kotlin.PublishedApi` is an annotation class with no fields which is applicable to any declaration.
   It may be applied to any declaration with `internal` visibility to make it available to `public` `inline` declarations.
   See [Declaration visibility section][Declaration visibility] for details.
+
+* `kotlin.BuilderInference`
+
+  Marks the annotated function of function argument as eligible for [builder-style type inference][Builder-style type inference].
+  See corresponding section for details.
+  
+  > Note: as of Kotlin 1.4.0, this annotation is experimental and, in order to use it in one's code, one must explicitly enable it using opt-in annotations given above.
+  > The particular marker class used to perform this is implementation-defined.
+
+* `kotlin.RestrictSuspension`
+
+  In some cases we may want to limit which [suspending functions] can be called in another suspending function with an extension receiver of a specific type; i.e., if we want to provide a coroutine-enabled DSL, but disallow the use of arbitrary suspending functions.
+  To do so, the type `T` of that extension receiver needs to be annotated with `kotlin.RestrictSuspension`, which enables the following limitations.
+
+  * Suspending functions with an extention receiver of type `T` are restricted from calling other suspending functions besides those accessible on this receiver.
+  * Suspending functions of type `T` can be called only on an extention receiver.

docs/scripts/build/directories.sh

@@ -183,11 +183,14 @@ It is the type of the result of [string interpolation][String interpolation expr
   
     Contains the ordinal of this enumeration constant, i.e., its position in the declaration, starting from zero.
 
-`kotlin.Enum<T>` provides the following methods.
+`kotlin.Enum<T>` provides the following member functions.
 
 * ```kotlin
   public override final fun compareTo(other: T): Int
   ```
+  
+    The implementation of `kotlin.Comparable`.
+    The result of `a.compareTo(b)` for enum class instances `a` and `b` is equivalent to `a.ordinal.compareTo(b.ordinal)`.
 
 * ```kotlin
   public override final fun equals(other: Any?): Boolean
@@ -197,13 +200,18 @@ It is the type of the result of [string interpolation][String interpolation expr
   public override final fun hashCode(): Int
   ```
 
-    > Note: the presence of these final methods ensures the semantics of equality and comparison for the enumeration objects, as they cannot be overridden by the user.
+    These member functions are defined to their default behaviour: only the same entry of an enum class is equal to itself and no other object.
+    Hash implementation is required to be consistent, but unspecified.
+
+    > Note: the presence of these final member functions ensures the semantics of equality and comparison for the enumeration objects, as they cannot be overridden by the user.
 
 * ```kotlin
   protected final fun clone(): Any
   ```
   
-    > Note: the `clone()` implementation throws an exception, as enumeration objects cannot be copied.
+    Throws an unspecified exception.
+  
+    > Note: the `clone()` implementation throws an exception, as enumeration objects cannot be copied and on some platforms `clone` function serves for copying.
 
 ### Built-in array types
 
@@ -217,6 +225,8 @@ It is final (i.e., cannot be inherited from) and has the following public constr
   
     Creates a new array with the specified size, where each element is calculated by calling the specified `init` function with the corresponding element's index.
     The function `init` is called for each array element sequentially starting from the first one.
+    This constructor is special in two ways: first, it is `inline` and inline constructors are not generally allowed in Kotlin.
+    Second, it is required for the parameter `T` to be instantiated with a [runtime-available type][Runtime-available types].
 
 `kotlin.Array<T>` provides the following methods and properties.