diff --git a/runtime/src/main/kotlin/kotlin/Annotations.kt b/runtime/src/main/kotlin/kotlin/Annotations.kt index edc4e8af6c4..4480588489f 100644 --- a/runtime/src/main/kotlin/kotlin/Annotations.kt +++ b/runtime/src/main/kotlin/kotlin/Annotations.kt @@ -1,21 +1,88 @@ package kotlin +import kotlin.annotation.AnnotationRetention.BINARY +import kotlin.annotation.AnnotationRetention.SOURCE +import kotlin.annotation.AnnotationTarget.* + +/** + * Marks the annotated class, function, property, variable or parameter as deprecated. + * @property message the message explaining the deprecation and recommending an alternative API to use. + * @property replaceWith if present, specifies a code fragment which should be used as a replacement for + * the deprecated API usage. + */ +@Target(CLASS, FUNCTION, PROPERTY, ANNOTATION_CLASS, CONSTRUCTOR, PROPERTY_SETTER, PROPERTY_GETTER, TYPEALIAS) +@MustBeDocumented +public annotation class Deprecated( + val message: String, + val replaceWith: ReplaceWith = ReplaceWith(""), + val level: DeprecationLevel = DeprecationLevel.WARNING +) + +/** + * Specifies a code fragment that can be used to replace a deprecated function, property or class. Tools such + * as IDEs can automatically apply the replacements specified through this annotation. + * + * @property expression the replacement expression. The replacement expression is interpreted in the context + * of the symbol being used, and can reference members of enclosing classes etc. + * For function calls, the replacement expression may contain argument names of the deprecated function, + * which will be substituted with actual parameters used in the call being updated. The imports used in the file + * containing the deprecated function or property are NOT accessible; if the replacement expression refers + * on any of those imports, they need to be specified explicitly in the [imports] parameter. + * @property imports the qualified names that need to be imported in order for the references in the + * replacement expression to be resolved correctly. + */ +@Target() +@Retention(BINARY) +@MustBeDocumented +public annotation class ReplaceWith(val expression: String, vararg val imports: String) + +/** + * Contains levels for deprecation levels. + */ +public enum class DeprecationLevel { + /** Usage of the deprecated element will be marked as a warning. */ + WARNING, + /** Usage of the deprecated element will be marked as an error. */ + ERROR, + /** Deprecated element will not be accessible from code. */ + HIDDEN +} + /** * Suppresses the given compilation warnings in the annotated element. * @property names names of the compiler diagnostics to suppress. */ -//@Target(CLASS, ANNOTATION_CLASS, PROPERTY, FIELD, LOCAL_VARIABLE, VALUE_PARAMETER, -// CONSTRUCTOR, FUNCTION, PROPERTY_GETTER, PROPERTY_SETTER, TYPE, EXPRESSION, FILE, TYPEALIAS) -@Target(AnnotationTarget.TYPE, AnnotationTarget.VALUE_PARAMETER, AnnotationTarget.EXPRESSION, - AnnotationTarget.LOCAL_VARIABLE, AnnotationTarget.FUNCTION) -//@Retention(SOURCE) +@Target(CLASS, ANNOTATION_CLASS, PROPERTY, FIELD, LOCAL_VARIABLE, VALUE_PARAMETER, + CONSTRUCTOR, FUNCTION, PROPERTY_GETTER, PROPERTY_SETTER, TYPE, EXPRESSION, FILE, TYPEALIAS) +@Retention(SOURCE) public annotation class Suppress(vararg val names: String) /** * Suppresses errors about variance conflict */ -@Target(AnnotationTarget.TYPE) -//@Retention(SOURCE) -//@MustBeDocumented +@Target(TYPE) +@Retention(SOURCE) +@MustBeDocumented public annotation class UnsafeVariance +/** + * Specifies the first version of Kotlin where a declaration has appeared. + * Using the declaration and specifying an older API version (via the `-api-version` command line option) will result in an error. + * + * @property version the version in the following formats: `.` or `..`, where major, minor and patch + * are non-negative integer numbers without leading zeros. + */ +@Target(CLASS, PROPERTY, FIELD, CONSTRUCTOR, FUNCTION, PROPERTY_GETTER, PROPERTY_SETTER, TYPEALIAS) +@Retention(AnnotationRetention.BINARY) +@MustBeDocumented +public annotation class SinceKotlin(val version: String) + + +/** + * Specifies that this part of internal API is effectively public exposed by using in public inline function + */ +@Target(AnnotationTarget.CLASS, AnnotationTarget.CONSTRUCTOR, AnnotationTarget.FUNCTION, AnnotationTarget.PROPERTY) +@Retention(AnnotationRetention.BINARY) +@MustBeDocumented +@SinceKotlin("1.1") +public annotation class PublishedApi \ No newline at end of file diff --git a/runtime/src/main/kotlin/kotlin/Function.kt b/runtime/src/main/kotlin/kotlin/Function.kt new file mode 100644 index 00000000000..8c46cd9d69d --- /dev/null +++ b/runtime/src/main/kotlin/kotlin/Function.kt @@ -0,0 +1,8 @@ +package kotlin + +/** + * Represents a value of a functional type, such as a lambda, an anonymous function or a function reference. + * + * @param R return type of the function. + */ +public interface Function diff --git a/runtime/src/main/kotlin/kotlin/annotation/Annotations.kt b/runtime/src/main/kotlin/kotlin/annotation/Annotations.kt new file mode 100644 index 00000000000..e466d0d198b --- /dev/null +++ b/runtime/src/main/kotlin/kotlin/annotation/Annotations.kt @@ -0,0 +1,101 @@ +/* + * Copyright 2010-2015 JetBrains s.r.o. + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +package kotlin.annotation + +/** + * Contains the list of code elements which are the possible annotation targets + */ +public enum class AnnotationTarget { + /** Class, interface or object, annotation class is also included */ + CLASS, + /** Annotation class only */ + ANNOTATION_CLASS, + /** Generic type parameter (unsupported yet) */ + TYPE_PARAMETER, + /** Property */ + PROPERTY, + /** Field, including property's backing field */ + FIELD, + /** Local variable */ + LOCAL_VARIABLE, + /** Value parameter of a function or a constructor */ + VALUE_PARAMETER, + /** Constructor only (primary or secondary) */ + CONSTRUCTOR, + /** Function (constructors are not included) */ + FUNCTION, + /** Property getter only */ + PROPERTY_GETTER, + /** Property setter only */ + PROPERTY_SETTER, + /** Type usage */ + TYPE, + /** Any expression */ + EXPRESSION, + /** File */ + FILE, + /** Type alias */ + @SinceKotlin("1.1") + TYPEALIAS +} + +/** + * Contains the list of possible annotation's retentions. + * + * Determines how an annotation is stored in binary output. + */ +public enum class AnnotationRetention { + /** Annotation isn't stored in binary output */ + SOURCE, + /** Annotation is stored in binary output, but invisible for reflection */ + BINARY, + /** Annotation is stored in binary output and visible for reflection (default retention) */ + RUNTIME +} + +/** + * This meta-annotation indicates the kinds of code elements which are possible targets of an annotation. + * + * If the target meta-annotation is not present on an annotation declaration, the annotation + * is applicable to any code element, except type parameters, type usages, expressions, and files. + * + * @property allowedTargets list of allowed annotation targets + */ +@Target(AnnotationTarget.ANNOTATION_CLASS) +@MustBeDocumented +public annotation class Target(vararg val allowedTargets: AnnotationTarget) + +/** + * This meta-annotation determines whether an annotation is stored in binary output and visible for reflection. By default, both are true. + * + * @property value necessary annotation retention (RUNTIME, BINARY or SOURCE) + */ +@Target(AnnotationTarget.ANNOTATION_CLASS) +public annotation class Retention(val value: AnnotationRetention = AnnotationRetention.RUNTIME) + +/** + * This meta-annotation determines that an annotation is applicable twice or more on a single code element + */ +@Target(AnnotationTarget.ANNOTATION_CLASS) +public annotation class Repeatable + +/** + * This meta-annotation determines that an annotation is a part of public API and therefore should be included in the generated + * documentation for the element to which the annotation is applied. + */ +@Target(AnnotationTarget.ANNOTATION_CLASS) +public annotation class MustBeDocumented \ No newline at end of file