Annotation option 'mustBeDocumented': definition, mapping from Kotlin to Java Documented and back, tests

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

@@ -83,9 +83,11 @@ public annotation class target(vararg val allowedTargets: AnnotationTarget)
  *
  * @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)
+ * @property mustBeDocumented true if annotation is a part of public API and therefore must be documented, otherwise false (default)
  */
 target(AnnotationTarget.ANNOTATION_CLASS)
 public annotation(retention = AnnotationRetention.SOURCE) class annotation (
         val retention: AnnotationRetention = AnnotationRetention.RUNTIME,
-        val repeatable: Boolean = false
+        val repeatable: Boolean = false,
+        val mustBeDocumented: Boolean = false
 )