[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() {