[FIR] Add KDocs for wrapped argument expressions

#KT-66124

compiler/fir/tree/gen/org/jetbrains/kotlin/fir/expressions/FirNamedArgumentExpression.kt

@@ -10,12 +10,26 @@ package org.jetbrains.kotlin.fir.expressions
 
 import org.jetbrains.kotlin.KtSourceElement
 import org.jetbrains.kotlin.fir.FirElement
+import org.jetbrains.kotlin.fir.expressions.impl.FirResolvedArgumentList
 import org.jetbrains.kotlin.fir.types.ConeKotlinType
 import org.jetbrains.kotlin.fir.visitors.FirTransformer
 import org.jetbrains.kotlin.fir.visitors.FirVisitor
 import org.jetbrains.kotlin.name.Name
 
 /**
+ * Represents a named argument `foo = bar` before and during body resolution phase.
+ *
+ * After body resolution, all [FirNamedArgumentExpression]s are removed from the FIR tree and the argument mapping must be
+ * retrieved from [FirResolvedArgumentList.mapping].
+ *
+ * For a named argument with spread operator `foo = *bar`, [isSpread] will be set to `true` but no additional
+ * [FirSpreadArgumentExpression] will be created as the [expression].
+ *
+ * **Special case vor varargs**: named arguments for `vararg` parameters are replaced with [FirSpreadArgumentExpression] with
+ * [FirSpreadArgumentExpression.isNamed] set to `true`.
+ *
+ * See [FirVarargArgumentsExpression] for the general structure of arguments of `vararg` parameters after resolution.
+ *
  * Generated from: [org.jetbrains.kotlin.fir.tree.generator.FirTreeBuilder.namedArgumentExpression]
  */
 abstract class FirNamedArgumentExpression : FirWrappedArgumentExpression() {

compiler/fir/tree/gen/org/jetbrains/kotlin/fir/expressions/FirSpreadArgumentExpression.kt

@@ -10,11 +10,31 @@ package org.jetbrains.kotlin.fir.expressions
 
 import org.jetbrains.kotlin.KtSourceElement
 import org.jetbrains.kotlin.fir.FirElement
+import org.jetbrains.kotlin.fir.expressions.impl.FirResolvedArgumentList
 import org.jetbrains.kotlin.fir.types.ConeKotlinType
 import org.jetbrains.kotlin.fir.visitors.FirTransformer
 import org.jetbrains.kotlin.fir.visitors.FirVisitor
 
 /**
+ * ### Up to and including body resolution phase
+ *
+ * Represents a spread expression `*foo`. If a spread expression is passed as named argument `foo = *bar`, it will be
+ * represented as an [FirNamedArgumentExpression] with [FirNamedArgumentExpression.isSpread] set to `true`.
+ *
+ * ### After body resolution phase
+ *
+ * Represents spread expressions `*foo` and named argument expressions for vararg parameters `foo = bar` and `foo = *bar`.
+ *
+ * If [isNamed] is `true`, it means the argument was passed in named form. The name is not saved since it's not required.
+ * To retrieve the argument mapping of a call, [FirResolvedArgumentList.mapping] must be used.
+ *
+ * If [isFakeSpread] is `true`, it means this expression is the argument to a `vararg` parameter that was passed in named form
+ * without a spread operator `*`.
+ *
+ * The information carried by [isNamed] and [isFakeSpread] is only relevant for some checkers. Otherwise,
+ * [FirSpreadArgumentExpression]s should be treated uniformly since they always represent an array that was passed to a
+ * `vararg` parameter and don't influence the resulting platform code.
+ *
  * Generated from: [org.jetbrains.kotlin.fir.tree.generator.FirTreeBuilder.spreadArgumentExpression]
  */
 abstract class FirSpreadArgumentExpression : FirWrappedArgumentExpression() {

compiler/fir/tree/gen/org/jetbrains/kotlin/fir/expressions/FirVarargArgumentsExpression.kt

@@ -15,6 +15,19 @@ import org.jetbrains.kotlin.fir.visitors.FirTransformer
 import org.jetbrains.kotlin.fir.visitors.FirVisitor
 
 /**
+ * [FirVarargArgumentsExpression]s are created during body resolution phase for arguments of `vararg` parameters.
+ *
+ * If one or multiple elements are passed to a `vararg` parameter, the will be wrapped with a [FirVarargArgumentsExpression]
+ * and [arguments] will contain the individual elements.
+ *
+ * If a named argument is passed to a `vararg` parameter, [arguments] will contain a single [FirSpreadArgumentExpression]
+ * with [FirSpreadArgumentExpression.isNamed] set to `true`.
+ *
+ * [FirSpreadArgumentExpression]s are kept as is in [arguments]. 
+ *
+ * If no element is passed to a `vararg` parameter, no [FirVarargArgumentsExpression] is created regardless of whether the
+ * parameter has a default value.
+ *
  * Generated from: [org.jetbrains.kotlin.fir.tree.generator.FirTreeBuilder.varargArgumentsExpression]
  */
 abstract class FirVarargArgumentsExpression : FirExpression() {

compiler/fir/tree/tree-generator/src/org/jetbrains/kotlin/fir/tree/generator/NodeConfigurator.kt

@@ -34,6 +34,7 @@ import org.jetbrains.kotlin.fir.tree.generator.context.AbstractFieldConfigurator
 import org.jetbrains.kotlin.fir.tree.generator.context.AbstractFirTreeBuilder.Companion.baseFirElement
 import org.jetbrains.kotlin.fir.tree.generator.context.type
 import org.jetbrains.kotlin.fir.tree.generator.model.*
+import org.jetbrains.kotlin.generators.tree.ArbitraryImportable
 import org.jetbrains.kotlin.generators.tree.StandardTypes
 import org.jetbrains.kotlin.generators.tree.TypeRef
 import org.jetbrains.kotlin.generators.tree.withArgs
@@ -613,15 +614,68 @@ object NodeConfigurator : AbstractFieldConfigurator<FirTreeBuilder>(FirTreeBuild
         spreadArgumentExpression.configure {
             +booleanField("isNamed")
             +booleanField("isFakeSpread")
+
+            element.kDoc = """
+                |### Up to and including body resolution phase
+                |
+                |Represents a spread expression `*foo`. If a spread expression is passed as named argument `foo = *bar`, it will be
+                |represented as an [FirNamedArgumentExpression] with [FirNamedArgumentExpression.isSpread] set to `true`.
+                |  
+                |### After body resolution phase
+                |
+                |Represents spread expressions `*foo` and named argument expressions for vararg parameters `foo = bar` and `foo = *bar`.
+                |
+                |If [isNamed] is `true`, it means the argument was passed in named form. The name is not saved since it's not required.
+                |To retrieve the argument mapping of a call, [FirResolvedArgumentList.mapping] must be used.
+                |
+                |If [isFakeSpread] is `true`, it means this expression is the argument to a `vararg` parameter that was passed in named form
+                |without a spread operator `*`.
+                |
+                |The information carried by [isNamed] and [isFakeSpread] is only relevant for some checkers. Otherwise,
+                |[FirSpreadArgumentExpression]s should be treated uniformly since they always represent an array that was passed to a
+                |`vararg` parameter and don't influence the resulting platform code.
+            """.trimMargin()
+            element.additionalImports.add(ArbitraryImportable("org.jetbrains.kotlin.fir.expressions.impl", "FirResolvedArgumentList"))
         }
 
         namedArgumentExpression.configure {
             +name
+
+            element.kDoc = """
+                |Represents a named argument `foo = bar` before and during body resolution phase.
+                |
+                |After body resolution, all [FirNamedArgumentExpression]s are removed from the FIR tree and the argument mapping must be
+                |retrieved from [FirResolvedArgumentList.mapping].
+                |
+                |For a named argument with spread operator `foo = *bar`, [isSpread] will be set to `true` but no additional
+                |[FirSpreadArgumentExpression] will be created as the [expression].
+                |
+                |**Special case vor varargs**: named arguments for `vararg` parameters are replaced with [FirSpreadArgumentExpression] with
+                |[FirSpreadArgumentExpression.isNamed] set to `true`.
+                |
+                |See [FirVarargArgumentsExpression] for the general structure of arguments of `vararg` parameters after resolution.
+            """.trimMargin()
+            element.additionalImports.add(ArbitraryImportable("org.jetbrains.kotlin.fir.expressions.impl", "FirResolvedArgumentList"))
         }
 
         varargArgumentsExpression.configure {
             +fieldList("arguments", expression)
             +field("coneElementTypeOrNull", coneKotlinTypeType, nullable = true)
+
+            element.kDoc = """
+                |[FirVarargArgumentsExpression]s are created during body resolution phase for arguments of `vararg` parameters.
+                |
+                |If one or multiple elements are passed to a `vararg` parameter, the will be wrapped with a [FirVarargArgumentsExpression]
+                |and [arguments] will contain the individual elements.
+                |
+                |If a named argument is passed to a `vararg` parameter, [arguments] will contain a single [FirSpreadArgumentExpression]
+                |with [FirSpreadArgumentExpression.isNamed] set to `true`.
+                |
+                |[FirSpreadArgumentExpression]s are kept as is in [arguments]. 
+                |
+                |If no element is passed to a `vararg` parameter, no [FirVarargArgumentsExpression] is created regardless of whether the
+                |parameter has a default value.
+            """.trimMargin()
         }
 
         samConversionExpression.configure {