New built-in annotations: Retention, Repeatable, MustBeDocumented

core/builtins/src/kotlin/annotation/Annotations.kt

@@ -89,3 +89,23 @@ public annotation(retention = AnnotationRetention.SOURCE, mustBeDocumented = tru
         val repeatable: Boolean = false,
         val mustBeDocumented: Boolean = false
 )
+
+/**
+ * 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 must be documented
+ */
+target(AnnotationTarget.ANNOTATION_CLASS)
+public annotation class MustBeDocumented

core/descriptors/src/org/jetbrains/kotlin/builtins/KotlinBuiltIns.java

@@ -180,6 +180,9 @@ public class KotlinBuiltIns {
         public final FqName annotation = annotationName("annotation");
         public final FqName annotationTarget = annotationName("AnnotationTarget");
         public final FqName annotationRetention = annotationName("AnnotationRetention");
+        public final FqName retention = annotationName("Retention");
+        public final FqName repeatable = annotationName("Repeatable");
+        public final FqName mustBeDocumented = annotationName("MustBeDocumented");
 
         public final FqName mutableList = fqName("MutableList");
         public final FqName mutableSet = fqName("MutableSet");
@@ -393,6 +396,21 @@ public class KotlinBuiltIns {
         return getAnnotationClassByName(FQ_NAMES.target.shortName());
     }
 
+    @NotNull
+    public ClassDescriptor getRetentionAnnotation() {
+        return getAnnotationClassByName(FQ_NAMES.retention.shortName());
+    }
+
+    @NotNull
+    public ClassDescriptor getRepeatableAnnotation() {
+        return getAnnotationClassByName(FQ_NAMES.repeatable.shortName());
+    }
+
+    @NotNull
+    public ClassDescriptor getMustBeDocumentedAnnotation() {
+        return getAnnotationClassByName(FQ_NAMES.mustBeDocumented.shortName());
+    }
+
     @NotNull
     public ClassDescriptor getAnnotationTargetEnum() {
         return getAnnotationClassByName(FQ_NAMES.annotationTarget.shortName());