kotlin.annotation package with annotations "target" and "annotation" and enums AnnotationTarget and AnnotationRetention introduced.

Targets for existing built-in annotations. Access to annotation package from packageFragmentProvider. Documentation for all classes in the package.
2015-06-26 13:56:47 +03:00
parent b162a65e85
commit 5126f01452
8 changed files with 123 additions and 7 deletions
@@ -58,6 +58,7 @@ public enum TopDownAnalyzerFacadeForJVM {
        List<ImportPath> list = new ArrayList<ImportPath>();
        list.add(new ImportPath("java.lang.*"));
        list.add(new ImportPath("kotlin.*"));
+        list.add(new ImportPath("kotlin.annotation.*"));
        list.add(new ImportPath("kotlin.jvm.*"));
        list.add(new ImportPath("kotlin.io.*"));
        // all classes from package "kotlin" mapped to java classes are imported explicitly so that they take priority over classes from java.lang
@@ -1261,11 +1261,11 @@ public object Unit {
    /*primary*/ private constructor Unit()
 }

-public final annotation class data : kotlin.Annotation {
+kotlin.annotation.target(allowedTargets = {AnnotationTarget.CLASSIFIER}) public final annotation class data : kotlin.Annotation {
    /*primary*/ public constructor data()
 }

-public final annotation class deprecated : kotlin.Annotation {
+kotlin.annotation.target(allowedTargets = {AnnotationTarget.CLASSIFIER, AnnotationTarget.FUNCTION, AnnotationTarget.PROPERTY, AnnotationTarget.ANNOTATION_CLASS, AnnotationTarget.CONSTRUCTOR, AnnotationTarget.PROPERTY_SETTER, AnnotationTarget.PROPERTY_GETTER}) public final annotation class deprecated : kotlin.Annotation {
    /*primary*/ public constructor deprecated(/*0*/ value: kotlin.String, /*1*/ replaceWith: kotlin.ReplaceWith = ...)
    internal final val replaceWith: kotlin.ReplaceWith
        internal final fun <get-replaceWith>(): kotlin.ReplaceWith
@@ -1273,7 +1273,7 @@ public final annotation class deprecated : kotlin.Annotation {
        internal final fun <get-value>(): kotlin.String
 }

-public final annotation class extension : kotlin.Annotation {
+kotlin.annotation.target(allowedTargets = {AnnotationTarget.TYPE}) public final annotation class extension : kotlin.Annotation {
    /*primary*/ public constructor extension()
 }

@@ -1293,12 +1293,12 @@ public final annotation class noinline : kotlin.Annotation {
    /*primary*/ public constructor noinline()
 }

-public final annotation class suppress : kotlin.Annotation {
+kotlin.annotation.target(allowedTargets = {AnnotationTarget.CLASSIFIER, AnnotationTarget.ANNOTATION_CLASS, AnnotationTarget.PROPERTY, AnnotationTarget.FIELD, AnnotationTarget.LOCAL_VARIABLE, AnnotationTarget.VALUE_PARAMETER, AnnotationTarget.CONSTRUCTOR, AnnotationTarget.FUNCTION, AnnotationTarget.PROPERTY_GETTER, AnnotationTarget.PROPERTY_SETTER, AnnotationTarget.TYPE, AnnotationTarget.EXPRESSION, AnnotationTarget.FILE}) public final annotation class suppress : kotlin.Annotation {
    /*primary*/ public constructor suppress(/*0*/ vararg names: kotlin.String /*kotlin.Array<out kotlin.String>*/)
    internal final val names: kotlin.Array<out kotlin.String>
        internal final fun <get-names>(): kotlin.Array<out kotlin.String>
 }

-public final annotation class tailRecursive : kotlin.Annotation {
+kotlin.annotation.target(allowedTargets = {AnnotationTarget.FUNCTION}) public final annotation class tailRecursive : kotlin.Annotation {
    /*primary*/ public constructor tailRecursive()
 }
@@ -16,20 +16,26 @@

 package kotlin

+import kotlin.annotation.*
+import kotlin.annotation.AnnotationTarget.*
+
 /**
 * Marks the annotated class as a data class. The compiler automatically generates
 * equals()/hashCode(), toString(), componentN() and copy() functions for data classes.
 * See [the Kotlin language documentation](http://kotlinlang.org/docs/reference/data-classes.html)
 * for more information.
 */
+target(CLASSIFIER)
 public annotation class data

 /**
- * Marks the annotated class, function or property as deprecated.
+ * Marks the annotated class, function, property, variable or parameter as deprecated.
 * @property value 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(CLASSIFIER, FUNCTION, PROPERTY, ANNOTATION_CLASS, CONSTRUCTOR, PROPERTY_SETTER, PROPERTY_GETTER,
+       LOCAL_VARIABLE, FIELD, VALUE_PARAMETER)
 public annotation class deprecated(val value: String, val replaceWith: ReplaceWith = ReplaceWith(""))

 /**
@@ -50,12 +56,15 @@ public annotation class ReplaceWith(val expression: String, vararg val imports:
 /**
 * Signifies that the annotated functional type represents an extension function.
 */
+target(TYPE)
 public annotation class extension

 /**
 * Suppresses the given compilation warnings in the annotated element.
 * @property names names of the compiler diagnostics to suppress.
 */
+target(CLASSIFIER, ANNOTATION_CLASS, PROPERTY, FIELD, LOCAL_VARIABLE, VALUE_PARAMETER,
+       CONSTRUCTOR, FUNCTION, PROPERTY_GETTER, PROPERTY_SETTER, TYPE, EXPRESSION, FILE)
 public annotation class suppress(vararg val names: String)

 /**
@@ -64,4 +73,5 @@ public annotation class suppress(vararg val names: String)
 * growing the stack depth. Tail call optimization is currently only supported by the JVM
 * backend.
 */
+target(FUNCTION)
 public annotation class tailRecursive
@@ -0,0 +1,91 @@
+/*
+ * 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 {
+    /** Package directive */
+    PACKAGE,
+    /** Class, interface or object, annotation class is also included */
+    CLASSIFIER,
+    /** 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
+}
+
+/**
+ * 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)
+public annotation class target(vararg val allowedTargets: AnnotationTarget)
+
+/**
+ * This special meta-annotation is used to declare an annotation and to set its base properties.
+ * So a class in Kotlin is an annotation if and only if it has the "annotation" meta-annotation.
+ *
+ * @property retention determines whether the annotation is stored in binary output and visible for reflection. By default, both are true.
+ * @property repeatable true if annotation is repeatable (applicable twice or more on a single code element), otherwise false (default)
+ */
+target(AnnotationTarget.ANNOTATION_CLASS)
+public annotation class annotation (
+        val retention: AnnotationRetention = AnnotationRetention.RUNTIME,
+        val repeatable: Boolean = false
+)
@@ -48,6 +48,7 @@ import static org.jetbrains.kotlin.resolve.DescriptorUtils.getFqName;
 public class KotlinBuiltIns {
    public static final Name BUILT_INS_PACKAGE_NAME = Name.identifier("kotlin");
    public static final FqName BUILT_INS_PACKAGE_FQ_NAME = FqName.topLevel(BUILT_INS_PACKAGE_NAME);
+    public static final FqName ANNOTATION_PACKAGE_FQ_NAME = BUILT_INS_PACKAGE_FQ_NAME.child(Name.identifier("annotation"));

    ////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////

@@ -115,7 +116,7 @@ public class KotlinBuiltIns {

        PackageFragmentProvider packageFragmentProvider = BuiltinsPackage.createBuiltInPackageFragmentProvider(
                storageManager, builtInsModule,
-                setOf(BUILT_INS_PACKAGE_FQ_NAME, BuiltinsPackage.getKOTLIN_REFLECT_FQ_NAME()),
+                setOf(BUILT_INS_PACKAGE_FQ_NAME, ANNOTATION_PACKAGE_FQ_NAME, BuiltinsPackage.getKOTLIN_REFLECT_FQ_NAME()),
                new BuiltInFictitiousFunctionClassFactory(storageManager, builtInsModule),
                new Function1<String, InputStream>() {
                    @Override
@@ -175,6 +176,8 @@ public class KotlinBuiltIns {
        public final FqName noinline = fqName("noinline");
        public final FqName inlineOptions = fqName("inlineOptions");
        public final FqName extension = fqName("extension");
+        public final FqName target = annotationName("target");
+        public final FqName annotation = annotationName("annotation");

        public final FqNameUnsafe kClass = new FqName("kotlin.reflect.KClass").toUnsafe();

@@ -198,6 +201,11 @@ public class KotlinBuiltIns {
        private static FqName fqName(@NotNull String simpleName) {
            return BUILT_INS_PACKAGE_FQ_NAME.child(Name.identifier(simpleName));
        }
+
+        @NotNull
+        private static FqName annotationName(@NotNull String simpleName) {
+            return ANNOTATION_PACKAGE_FQ_NAME.child(Name.identifier(simpleName));
+        }
    }

    ////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
@@ -16,6 +16,7 @@

 package org.jetbrains.kotlin.builtins.functions

+import org.jetbrains.kotlin.builtins.KotlinBuiltIns
 import org.jetbrains.kotlin.builtins.functions.FunctionClassDescriptor.Kind
 import org.jetbrains.kotlin.descriptors.ClassDescriptor
 import org.jetbrains.kotlin.descriptors.ModuleDescriptor
@@ -37,6 +38,8 @@ public class BuiltInFictitiousFunctionClassFactory(

    companion object {
        platformStatic public fun parseClassName(className: String, packageFqName: FqName): KindWithArity? {
+            // There is no functions in kotlin.annotation package
+            if (packageFqName == KotlinBuiltIns.ANNOTATION_PACKAGE_FQ_NAME) return null
            val kind = FunctionClassDescriptor.Kind.byPackage(packageFqName) ?: return null

            val prefix = kind.classNamePrefix
@@ -43,6 +43,7 @@ public final class TopDownAnalyzerFacadeForJS {
    public static final List<ImportPath> DEFAULT_IMPORTS = ImmutableList.of(
            new ImportPath("java.lang.*"),
            new ImportPath("kotlin.*"),
+            new ImportPath("kotlin.annotation.*"),
            new ImportPath("kotlin.js.*")
    );

@@ -2,6 +2,7 @@
    <fileset id="kotlin.builtin.files" dir="${basedir}/core/builtins">
        <include name="native/kotlin/Iterator.kt"/>
        <include name="native/kotlin/Collections.kt"/>
+        <include name="src/kotlin/annotation/Annotations.kt"/>
        <include name="src/kotlin/Function.kt"/>
        <include name="src/kotlin/Iterators.kt"/>
        <include name="src/kotlin/Range.kt"/>
@@ -16,6 +17,7 @@

        <fileset dir="${basedir}/core/builtins/src">
            <include name="kotlin/reflect/**/*.kt"/>
+            <include name="kotlin/annotation/Annotations.kt"/>
        </fileset>

        <fileset dir="${basedir}/libraries/stdlib/src">