diff --git a/compiler/fir/tree/gen/org/jetbrains/kotlin/fir/FirElement.kt b/compiler/fir/tree/gen/org/jetbrains/kotlin/fir/FirElement.kt index 793bb1b9bb4..c5bfc9eb10e 100644 --- a/compiler/fir/tree/gen/org/jetbrains/kotlin/fir/FirElement.kt +++ b/compiler/fir/tree/gen/org/jetbrains/kotlin/fir/FirElement.kt @@ -19,18 +19,53 @@ import org.jetbrains.kotlin.fir.visitors.FirVisitorVoid interface FirElement { val source: KtSourceElement? + /** + * Runs the provided [visitor] on the FIR subtree with the root at this node. + * + * @param visitor The visitor to accept. + * @param data An arbitrary context to pass to each invocation of [visitor]'s methods. + * @return The value returned by the topmost `visit*` invocation. + */ fun accept(visitor: FirVisitor, data: D): R = visitor.visitElement(this, data) + /** + * Runs the provided [transformer] on the FIR subtree with the root at this node. + * + * @param transformer The transformer to use. + * @param data An arbitrary context to pass to each invocation of [transformer]'s methods. + * @return The transformed node. + */ @Suppress("UNCHECKED_CAST") fun transform(transformer: FirTransformer, data: D): E = transformer.transformElement(this, data) as E fun accept(visitor: FirVisitorVoid) = accept(visitor, null) + /** + * Runs the provided [visitor] on subtrees with roots in this node's children. + * + * Basically, calls `accept(visitor, data)` on each child of this node. + * + * Does **not** run [visitor] on this node itself. + * + * @param visitor The visitor for children to accept. + * @param data An arbitrary context to pass to each invocation of [visitor]'s methods. + */ fun acceptChildren(visitor: FirVisitor, data: D) fun acceptChildren(visitor: FirVisitorVoid) = acceptChildren(visitor, null) + /** + * Recursively transforms this node's children *in place* using [transformer]. + * + * Basically, executes `this.child = this.child.transform(transformer, data)` for each child of this node. + * + * Does **not** run [transformer] on this node itself. + * + * @param transformer The transformer to use for transforming the children. + * @param data An arbitrary context to pass to each invocation of [transformer]'s methods. + * @return `this` + */ fun transformChildren(transformer: FirTransformer, data: D): FirElement } diff --git a/compiler/fir/tree/tree-generator/src/org/jetbrains/kotlin/fir/tree/generator/printer/element.kt b/compiler/fir/tree/tree-generator/src/org/jetbrains/kotlin/fir/tree/generator/printer/element.kt index 709e910e46d..62271e620c9 100644 --- a/compiler/fir/tree/tree-generator/src/org/jetbrains/kotlin/fir/tree/generator/printer/element.kt +++ b/compiler/fir/tree/tree-generator/src/org/jetbrains/kotlin/fir/tree/generator/printer/element.kt @@ -23,16 +23,14 @@ private class ElementPrinter(printer: SmartPrinter) : AbstractElementPrinter, visitorClass: ClassRef, hasImplementation: Boolean, - kDoc: String?, + treeName: String, ) { if (!element.hasAcceptMethod) return println() - printKDoc(kDoc) val resultTP = TypeVariable("R") + val visitorParameter = FunctionParameter("visitor", visitorClass.withArgs(resultTP, dataTP)) + if (element.isRootElement) { + printKDoc( + """ + Runs the provided [${visitorParameter.name}] on the $treeName subtree with the root at this node. + + @param ${visitorParameter.name} The visitor to accept. + @param ${dataParameter.name} An arbitrary context to pass to each invocation of [${visitorParameter.name}]'s methods. + @return The value returned by the topmost `visit*` invocation. + """.trimIndent() + ) + } printFunctionDeclaration( name = "accept", - parameters = listOf( - FunctionParameter("visitor", visitorClass.withArgs(resultTP, dataTP)), - dataParameter, - ), + parameters = listOf(visitorParameter, dataParameter), returnType = resultTP, typeParameters = listOf(resultTP, dataTP), override = !element.isRootElement, @@ -175,7 +183,7 @@ fun SmartPrinter.printAcceptMethod( if (hasImplementation) { println(" =") withIndent { - print("visitor.", element.visitFunctionName, "(this, ", dataParameter.name, ")") + print(visitorParameter.name, ".", element.visitFunctionName, "(this, ", dataParameter.name, ")") } } println() @@ -187,20 +195,28 @@ fun SmartPrinter.printTransformMethod( transformerClass: ClassRef, implementation: String?, returnType: TypeRefWithNullability, - kDoc: String?, + treeName: String, ) { if (!element.hasTransformMethod) return println() - printKDoc(kDoc) + val transformerParameter = FunctionParameter("transformer", transformerClass.withArgs(dataTP)) + if (element.isRootElement) { + printKDoc( + """ + Runs the provided [${transformerParameter.name}] on the $treeName subtree with the root at this node. + + @param ${transformerParameter.name} The transformer to use. + @param ${dataParameter.name} An arbitrary context to pass to each invocation of [${transformerParameter.name}]'s methods. + @return The transformed node. + """.trimIndent() + ) + } if (returnType is TypeParameterRef && implementation != null) { println("@Suppress(\"UNCHECKED_CAST\")") } printFunctionDeclaration( name = "transform", - parameters = listOf( - FunctionParameter("transformer", transformerClass.withArgs(dataTP)), - dataParameter, - ), + parameters = listOf(transformerParameter, dataParameter), returnType = returnType, typeParameters = listOfNotNull(returnType as? TypeVariable, dataTP), override = !element.isRootElement, @@ -221,17 +237,27 @@ fun SmartPrinter.printAcceptChildrenMethod( visitorResultType: TypeRef, modality: Modality? = null, override: Boolean = false, - kDoc: String?, ) { if (!element.hasAcceptChildrenMethod) return println() - printKDoc(kDoc) + val visitorParameter = FunctionParameter("visitor", visitorClass.withArgs(visitorResultType, dataTP)) + if (!override) { + printKDoc( + """ + Runs the provided [${visitorParameter.name}] on subtrees with roots in this node's children. + + Basically, calls `accept(${visitorParameter.name}, ${dataParameter.name})` on each child of this node. + + Does **not** run [${visitorParameter.name}] on this node itself. + + @param ${visitorParameter.name} The visitor for children to accept. + @param ${dataParameter.name} An arbitrary context to pass to each invocation of [${visitorParameter.name}]'s methods. + """.trimIndent() + ) + } printFunctionDeclaration( name = "acceptChildren", - parameters = listOf( - FunctionParameter("visitor", visitorClass.withArgs(visitorResultType, dataTP)), - dataParameter, - ), + parameters = listOf(visitorParameter, dataParameter), returnType = StandardTypes.unit, typeParameters = listOfNotNull(visitorResultType as? TypeVariable, dataTP), modality = modality, @@ -246,17 +272,27 @@ fun SmartPrinter.printTransformChildrenMethod( returnType: TypeRef, modality: Modality? = null, override: Boolean = false, - kDoc: String?, ) { if (!element.hasTransformChildrenMethod) return println() - printKDoc(kDoc) + val transformerParameter = FunctionParameter("transformer", transformerClass.withArgs(dataTP)) + if (!override) { + printKDoc( + """ + Recursively transforms this node's children *in place* using [${transformerParameter.name}]. + + Basically, executes `this.child = this.child.transform(${transformerParameter.name}, ${dataParameter.name})` for each child of this node. + + Does **not** run [${transformerParameter.name}] on this node itself. + + @param ${transformerParameter.name} The transformer to use for transforming the children. + @param ${dataParameter.name} An arbitrary context to pass to each invocation of [${transformerParameter.name}]'s methods. + """.trimIndent() + (if (returnType == StandardTypes.unit) "" else "\n@return `this`") + ) + } printFunctionDeclaration( name = "transformChildren", - parameters = listOf( - FunctionParameter("transformer", transformerClass.withArgs(dataTP)), - dataParameter, - ), + parameters = listOf(transformerParameter, dataParameter), returnType = returnType, typeParameters = listOf(dataTP), modality = modality,