From 153ee3bc4b7988fa729827d4d3347186c24b3249 Mon Sep 17 00:00:00 2001
From: Dmitrii Gridin <dmitry.gridin@jetbrains.com>
Date: Thu, 2 Feb 2023 14:19:42 +0100
Subject: [PATCH] [SLC] AdditionalAnnotationsProvider: add kdoc

^KT-56046
---
 .../AdditionalAnnotationsProvider.kt          | 31 +++++++++++++++++++
 1 file changed, 31 insertions(+)

diff --git a/analysis/symbol-light-classes/src/org/jetbrains/kotlin/light/classes/symbol/annotations/AdditionalAnnotationsProvider.kt b/analysis/symbol-light-classes/src/org/jetbrains/kotlin/light/classes/symbol/annotations/AdditionalAnnotationsProvider.kt
index 2eb1c02a1be..0643e8f7033 100644
--- a/analysis/symbol-light-classes/src/org/jetbrains/kotlin/light/classes/symbol/annotations/AdditionalAnnotationsProvider.kt
+++ b/analysis/symbol-light-classes/src/org/jetbrains/kotlin/light/classes/symbol/annotations/AdditionalAnnotationsProvider.kt
@@ -8,7 +8,25 @@ package org.jetbrains.kotlin.light.classes.symbol.annotations
 import com.intellij.psi.PsiAnnotation
 import com.intellij.psi.PsiModifierList
 
+/**
+ * This class provides more annotation in addition to [AnnotationsProvider].
+ *
+ * [EmptyAdditionalAnnotationsProvider] is just an empty provider.
+ * [SimpleAdditionalAnnotationsProvider] is a collection of additional annotations.
+ * [CompositeAdditionalAnnotationsProvider] is a composition of some [AdditionalAnnotationsProvider].
+ *
+ * @see [LazyAnnotationsBox]
+ */
 internal sealed interface AdditionalAnnotationsProvider {
+    /**
+     * Adds new annotations to [currentRawAnnotations] and [foundQualifiers].
+     * [currentRawAnnotations] and [foundQualifiers] must be consistent with each other.
+     * A parent for all new annotations must be [owner].
+     *
+     * @param currentRawAnnotations a list of already presented annotations
+     * @param foundQualifiers a list of already presented qualifiers. Used to optimize computation
+     * @param owner an owner for new annotations
+     */
     fun addAllAnnotations(currentRawAnnotations: MutableList<in PsiAnnotation>, foundQualifiers: MutableSet<String>, owner: PsiModifierList)
 
     /**
@@ -16,8 +34,21 @@ internal sealed interface AdditionalAnnotationsProvider {
      * (should be processed without [LazyAnnotationsBox.getOrComputeCachedAnnotations] call)
      */
     fun isSpecialQualifier(qualifiedName: String): Boolean
+
+    /**
+     * The resulted annotation must be presented among all annotations after [addAllAnnotations]
+     *
+     * @param annotationsBox an owner of [AdditionalAnnotationsProvider]
+     * @param qualifiedName a **special** ([isSpecialQualifier] must be **true** for it) qualified name for a new annotation
+     * @param owner an owner for a new annotation
+     *
+     * @return a new annotation with [qualifiedName]
+     */
     fun findSpecialAnnotation(annotationsBox: LazyAnnotationsBox, qualifiedName: String, owner: PsiModifierList): PsiAnnotation?
 
+    /**
+     * Adds a new annotation with [qualifier] name to [currentRawAnnotations] and [foundQualifiers] if not already present
+     */
     fun addSimpleAnnotationIfMissing(
         qualifier: String,
         currentRawAnnotations: MutableList<in PsiAnnotation>,