Merge remote-tracking branch 'origin/dev' into dev

Author: belyaev-mikhail

docs/src/md/kotlin.core/annotations.md

@@ -7,7 +7,7 @@ Values of annotation types cannot be created directly, but can be operated on wh
 ### Annotation values
 
 An annotation value is a value of a special [annotation type][Annotation declarations].
-An annotation type is a special kind of class type which is allowed to include properties of the following types:
+An annotation type is a special kind of class type which is allowed to include read-only properties of the following types:
 
 - [Integer types][Built-in integer types];
 - [Enum types][Enum class declaration];
@@ -16,24 +16,24 @@ An annotation type is a special kind of class type which is allowed to include p
 - [Arrays][Array types] of any type listed above.
 
 Annotation classes are not allowed to have any member functions, constructors or mutable properties.
-They are also not allowed to have base classes and are considered to be implicitly derived from `kotlin.Annotation`.
+They are also not allowed to have declared supertypes and are considered to be implicitly derived from `kotlin.Annotation`.
 
 ### Annotation retention
 
-The retention level of an annotation declares which compilation artifacts a particular compiler on a particular platform *retain* this kind of annotation.
+The retention level of an annotation declares which compilation artifacts (for a particular compiler on a particular platform) *retain* this kind of annotation.
 There are the following types of retention available:
 
 - Source retention (accessible by source-processing tools);
 - Binary retention (retained in compilation artifacts);
 - Runtime retention (accessible at runtime).
 
-    Each subsequent level inherits what is accessible on the previous levels.
+  > Each subsequent level inherits what is accessible on the previous levels.
 
-For availability and particular ways of accessing the metadata specified by these annotations please refer to the corresponding platforms' documentation.
+For availability and particular ways of accessing the metadata specified by these annotations please refer to the corresponding platform-specific documentation.
 
 ### Annotation targets
 
-The *targets* of a particular type of annotations is the kind of program entity which this annotations may be placed on.
+The *target* of a particular type of annotations is the kind of program entity which this annotations may be placed on.
 There are the following targets available:
 
 - A [class declaration][Class declaration] (including annotation classes);
@@ -65,27 +65,33 @@ TODO(Anything else?)
 
 * `kotlin.annotation.Retention`
 
-  `kotlin.annotation.Retention` is an annotation that is only used in annotation classes to specify annotation retention.
+  `kotlin.annotation.Retention` is an annotation which is only used on annotation classes to specify their annotation retention level.
   It has the following single field:
-  ```kotlin
-  val value: AnnotationRetention = AnnotationRetention.RUNTIME
-  ```
+
+  * ```kotlin
+    val value: AnnotationRetention = AnnotationRetention.RUNTIME
+    ```
+
+    The retention level of the annotated annotation.
 
-  `kotlin.annotation.AnnotationRetention` is an enum class with the following values (see [annotation targets section][Annotation targets] for details):
+  `kotlin.annotation.AnnotationRetention` is an enum class with the following values (see [Annotation retention section][Annotation retention] for details):
 
   * `SOURCE`;
   * `BINARY`;
   * `RUNTIME`.
 
 * `kotlin.annotation.Target`
 
-  `kotlin.annotation.Target` is an annotation that is only used in annotation classes to specify targets this annotation is valid for.
+  `kotlin.annotation.Target` is an annotation which is only used on annotation classes to specify targets those annotations are valid for.
   It has the following single field:
-  ```kotlin
-  vararg val allowedTargets: AnnotationTarget
-  ```
 
-  `kotlin.annotation.AnnotationTarget` is an enum class with the following values (see [annotation retention section][Annotation retention] for details):
+  * ```kotlin
+    vararg val allowedTargets: AnnotationTarget
+    ```
+  
+    The allowed annotation targets of the annotated annotation.
+
+  `kotlin.annotation.AnnotationTarget` is an enum class with the following values (see [Annotation targets section][Annotation targets] for details):
 
   * `CLASS`;
   * `ANNOTATION_CLASS`;
@@ -105,7 +111,7 @@ TODO(Anything else?)
 
 * `kotlin.annotation.Repeatable`
 
-  `kotlin.annotation.Repeatable` is an annotation that is only used in annotation classes to specify whether this particular annotation is repeatable.
+  `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`
@@ -116,22 +122,23 @@ TODO(Anything else?)
     val level: Level = Level.ERROR
     ```
 
-    The severity level of the experimental status with two values: `Level.WARNING` and `Level.ERROR`
+    The severity level of the experimental status with two possible values: `Level.WARNING` and `Level.ERROR`.
 
   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
     vararg val markerClass: KClass<out Annotation>
     ```
 
-    The classes this annotation is allowing to use
+    The classes which this annotation allows to use.
 
-  This annotation is used to explicitly mark declarations that use experimental features marked by `kotlin.Experimental` .
+  This annotation is used to explicitly mark declarations which use experimental features marked by `kotlin.Experimental`.
 
-  It is implementation-defined on how these annotations are processed.
+  It is implementation-defined how this annotation is processed.
 
-  TODO(experimental status is still experimental itself)
+  TODO(Experimental status is still experimental itself)
 
 * `kotlin.Deprecated` / `kotlin.ReplaceWith`
 
@@ -141,19 +148,19 @@ TODO(Anything else?)
     val message: String
     ```
 
-    The message supporting the deprecation
+    A message supporting the deprecation.
 
   * ```kotlin
     val replaceWith: ReplaceWith = ReplaceWith("")
     ```
 
-    An optional replacement for deprecated code
+    An optional replacement for the deprecated code.
 
   * ```kotlin
     val level: DeprecationLevel = DeprecationLevel.WARNING
     ```
 
-    The deprecation level
+    The deprecation level with three possible values: `DeprecationLevel.WARNING`, `DeprecationLevel.ERROR` and `DeprecationLevel.HIDDEN`.
 
   `kotlin.ReplaceWith` is itself an annotation class containing the information on how to perform the replacement in case it is provided.
   It has the following fields:
@@ -162,21 +169,19 @@ TODO(Anything else?)
     val expression: String
     ```
 
-    The replacement code
+    The replacement code.
 
   * ```kotlin
     vararg val imports: String
     ```
 
-    The array of imports needed for the replacement code to work correctly
+    An array of imports needed for the replacement code to work correctly.
 
-  `kotlin.DeprecationLevel` is an enum class with three values: `WARNING`, `ERROR` and `HIDDEN`.
+  `kotlin.Deprecated` is a built-in annotation supporting the deprecation cycle for declarations: marking some declarations as outdated, soon to be replaced with other declarations, or not recommended for use.
+  It is implementation-defined how this annotation is processed, with the following recommendations:
 
-  `kotlin.Deprecated` is a builtin annotation supporting the deprecation cycle for declarations: marking that some declarations are outdated, soon to be replaced with other declarations or not recommended.
-  It is implementation-defined how this annotation is handled, with the following recommendations:
-
-  * Attempting to use a declaration with deprecation level of `kotlin.DeprecationLevel.WARNING` should produce a compile-time warning;
-  * Attempting to use a declaration with deprecation level of `kotlin.DeprecationLevel.ERROR` should produce a compile-time error.
+  * Attempting to use a declaration with deprecation level of `DeprecationLevel.WARNING` should produce a compile-time warning;
+  * Attempting to use a declaration with deprecation level of `DeprecationLevel.ERROR` should produce a compile-time error.
 
 * `kotlin.Suppress`
 
@@ -186,10 +191,10 @@ TODO(Anything else?)
     vararg val names: String
     ```
 
-    The names of features this annotation is suppressing
+    The names of features this annotation is suppressing.
 
   `kotlin.Suppress` is used to optionally mark any piece of code as suppressing some language feature, such as a compiler warning, an IDE mechanism or a language feature.
-  The names of features that one can suppress with this annotation is implementation-defined, as is the processing of this annotation itself.
+  The names of features which one can suppress with this annotation are implementation-defined, as is the processing of this annotation itself.
 
 * `kotlin.SinceKotlin`
 
@@ -199,32 +204,27 @@ TODO(Anything else?)
     val version: String
     ```
 
-    The version of Kotlin language
+    The version of Kotlin language.
 
-  `kotlin.SinceKotlin` is used to mark that a specific declaration is only available since some particular version of the language and above it.
+  `kotlin.SinceKotlin` is used to mark a declaration which is only available since a particular version of the language.
   These mostly refer to standard library declarations.
-  It is implementation-defined how this annotations are processed.
+  It is implementation-defined how this annotation is processed.
 
 * `kotlin.UnsafeVariance`
 
-  `kotlin.UnsafeVariance` is an annotation class with no fields that is only applicable to types.
-  Any declaration marked by this annotation explicitly states that the [variance][Type parameter variance] errors arising for this particular type are to be ignored by the compiler.
+  `kotlin.UnsafeVariance` is an annotation class with no fields which is only applicable to types.
+  Any type instance marked by this annotation explicitly states that the [variance][Type parameter variance] errors arising for this particular type instance are to be ignored by the compiler.
 
 * `kotlin.DslMarker`
 
-  `kotlin.DslMarker` is an annotation class with no fields that is applicable only to other annotation classes.
+  `kotlin.DslMarker` is an annotation class with no fields which is applicable only to other annotation classes.
   An annotation class annotated with `kotlin.DslMarker` is marked as a marker of a specific DSL (domain-specific language).
   Any type annotated with such a marker is said to belong to that specific DSL.
   This affects [overload resolution][Overload resolution] in the following way: no two implicit receivers with types belonging to the same DSL are available in the same scope.
-  See [overload resolution section][Overload resolution] for details.
-  
-  TODO(sync with receivers???)
+  See [Overload resolution section][Receivers] for details.
 
 * `kotlin.PublishedApi`
 
-  `kotlin.PublishedApi` is an annotation class with no fields that is applicable to any declarations.
-  This may be applied to any declarations with `internal` visibility to be visible to `public` `inline` declarations.
-  See [the visibility section][Declaration visibility] for details.
-
-
-
+  `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.

docs/src/md/kotlin.core/builtins.md

@@ -271,6 +271,10 @@ This function is used to implement [comparison operators][Comparison expressions
 `kotlin.Function<out R>` is the base classifier type of all [function types][Function types].
 See the relevant section for details.
 
+### Built-in annotation types
+
+Kotlin has a number of built-in [annotation types][Annotations], which are covered in more detail [here][Built-in annotations].
+
 ### Reflection support builtin types
 
 #### `kotlin.reflect.KClass`

docs/src/md/kotlin.core/overload-resolution.md

@@ -40,6 +40,8 @@ The available receivers are prioritized in the following way:
 
 > Important: these rules mean implicit receivers are always totally ordered w.r.t. their priority, as no two implicit receivers can have the same priority.
 
+> Important: DSL-specific annotations (marked with [`kotlin.DslMarker`][Built-in annotations] annotation) change the availability of implicit receivers in the following way: for all types marked with a particular DSL-specific annotation, only the highest priority implicit receiver is available in a given scope. 
+
 The implicit receiver having the highest priority is also called the _default implicit receiver_.
 The default implicit receiver is available in a scope as `this`.
 Other available receivers may be accessed using [labeled this-expressions][This-expressions].