From d16cc668cd87f6c389f745f9d84852345524555e Mon Sep 17 00:00:00 2001 From: Kirill Rakhman Date: Mon, 4 Mar 2024 16:52:39 +0100 Subject: [PATCH] [FIR] Add KDocs for wrapped argument expressions #KT-66124 --- .../expressions/FirNamedArgumentExpression.kt | 14 +++++ .../FirSpreadArgumentExpression.kt | 20 +++++++ .../FirVarargArgumentsExpression.kt | 13 +++++ .../fir/tree/generator/NodeConfigurator.kt | 54 +++++++++++++++++++ 4 files changed, 101 insertions(+) diff --git a/compiler/fir/tree/gen/org/jetbrains/kotlin/fir/expressions/FirNamedArgumentExpression.kt b/compiler/fir/tree/gen/org/jetbrains/kotlin/fir/expressions/FirNamedArgumentExpression.kt index ff451294199..dff27473102 100644 --- a/compiler/fir/tree/gen/org/jetbrains/kotlin/fir/expressions/FirNamedArgumentExpression.kt +++ b/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() { diff --git a/compiler/fir/tree/gen/org/jetbrains/kotlin/fir/expressions/FirSpreadArgumentExpression.kt b/compiler/fir/tree/gen/org/jetbrains/kotlin/fir/expressions/FirSpreadArgumentExpression.kt index 8cab5544454..77c386cc6b6 100644 --- a/compiler/fir/tree/gen/org/jetbrains/kotlin/fir/expressions/FirSpreadArgumentExpression.kt +++ b/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() { diff --git a/compiler/fir/tree/gen/org/jetbrains/kotlin/fir/expressions/FirVarargArgumentsExpression.kt b/compiler/fir/tree/gen/org/jetbrains/kotlin/fir/expressions/FirVarargArgumentsExpression.kt index 86a65a37d50..f0c8e096c83 100644 --- a/compiler/fir/tree/gen/org/jetbrains/kotlin/fir/expressions/FirVarargArgumentsExpression.kt +++ b/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() { diff --git a/compiler/fir/tree/tree-generator/src/org/jetbrains/kotlin/fir/tree/generator/NodeConfigurator.kt b/compiler/fir/tree/tree-generator/src/org/jetbrains/kotlin/fir/tree/generator/NodeConfigurator.kt index 2cba55d4201..58361425e97 100644 --- a/compiler/fir/tree/tree-generator/src/org/jetbrains/kotlin/fir/tree/generator/NodeConfigurator.kt +++ b/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(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 {