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
@@ -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