[AA] KtAnnotationApplicationInfo: add more information to kdoc

^KT-56046

analysis/analysis-api/src/org/jetbrains/kotlin/analysis/api/annotations/KtAnnotated.kt

@@ -17,6 +17,9 @@ public interface KtAnnotated {
 /**
  * A list of annotations applied.
  *
+ * To check if annotation is present, please use [hasAnnotation].
+ * [annotationInfos] is more preferable if suits your needs because it is lightweight.
+ *
  * @see [KtAnnotationsList.annotations]
  */
 public val KtAnnotated.annotations: List<KtAnnotationApplicationWithArgumentsInfo>

analysis/analysis-api/src/org/jetbrains/kotlin/analysis/api/annotations/KtAnnotationApplication.kt

@@ -16,6 +16,9 @@ import org.jetbrains.kotlin.psi.KtCallElement
  * - For declarations: `@Deprecated("Should not be used") fun foo(){}`
  * - For types: `fun foo(x: List<@A Int>){}`
  * - Inside another annotation (`B` is annotation here): `@A(B()) fun foo(){}
+ *
+ * @see KtAnnotationApplicationInfo
+ * @see KtAnnotationApplicationWithArgumentsInfo
  */
 public sealed interface KtAnnotationApplication {
     /**

analysis/analysis-api/src/org/jetbrains/kotlin/analysis/api/annotations/KtAnnotationApplicationInfo.kt

@@ -10,11 +10,19 @@ import org.jetbrains.kotlin.name.ClassId
 import org.jetbrains.kotlin.psi.KtCallElement
 
 /**
- * Info of annotation to some declaration or type.
+ * A lightweight implementation of [KtAnnotationApplication].
+ * Should be used instead of [KtAnnotationApplicationWithArgumentsInfo] where possible to avoid redundant resolve.
  *
- * Some examples:
+ * Example:
- * - For declarations: `@Deprecated("Should not be used") fun foo(){}`
+ * ```
- * - For types: `fun foo(x: List<@A Int>){}`
+ * @Anno1(1) @Anno2
+ * class Foo
+ * ```
+ * In this case if you don't want to process [KtAnnotationApplicationWithArgumentsInfo.arguments]
+ * you can call [KtAnnotated.annotationInfos] to get all necessary information.
+ *
+ * @see KtAnnotated.annotationInfos
+ * @see KtAnnotationApplicationWithArgumentsInfo
  */
 public data class KtAnnotationApplicationInfo(
     public override val classId: ClassId?,

analysis/analysis-api/src/org/jetbrains/kotlin/analysis/api/annotations/KtAnnotationApplicationWithArgumentsInfo.kt

@@ -9,6 +9,10 @@ import org.jetbrains.kotlin.descriptors.annotations.AnnotationUseSiteTarget
 import org.jetbrains.kotlin.name.ClassId
 import org.jetbrains.kotlin.psi.KtCallElement
 
+/**
+ * @see KtAnnotated.annotations
+ * @see KtAnnotationApplicationInfo
+ */
 public data class KtAnnotationApplicationWithArgumentsInfo(
     override val classId: ClassId?,
     override val psi: KtCallElement?,

analysis/analysis-api/src/org/jetbrains/kotlin/analysis/api/annotations/KtAnnotationsList.kt

@@ -18,6 +18,7 @@ public abstract class KtAnnotationsList : KtLifetimeOwner {
      * A list of annotations applied.
      *
      * To check if annotation is present, please use [hasAnnotation].
+     * [annotationInfos] is more preferable if suits your needs as a lightweight.
      *
      * @see KtAnnotationApplication
      */