From cab87eba21a7914d9f64344d7e062ba122a468a2 Mon Sep 17 00:00:00 2001 From: Sergej Jaskiewicz Date: Mon, 11 Dec 2023 19:54:45 +0100 Subject: [PATCH] [SIR, FIR generators] Add KDocs for visitor-related methods of elements --- .../org/jetbrains/kotlin/fir/FirElement.kt | 14 ++++ .../tree/generator/printer/ElementPrinter.kt | 7 +- .../generators/tree/printer/printUtils.kt | 82 +++++++++++++------ .../org/jetbrains/kotlin/sir/SirElement.kt | 14 ++++ .../tree/generator/printer/ElementPrinter.kt | 2 +- 5 files changed, 92 insertions(+), 27 deletions(-) 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 c5bfc9eb10e..07fd83dee21 100644 --- a/compiler/fir/tree/gen/org/jetbrains/kotlin/fir/FirElement.kt +++ b/compiler/fir/tree/gen/org/jetbrains/kotlin/fir/FirElement.kt @@ -40,6 +40,11 @@ interface FirElement { fun transform(transformer: FirTransformer, data: D): E = transformer.transformElement(this, data) as E + /** + * Runs the provided [visitor] on the FIR subtree with the root at this node. + * + * @param visitor The visitor to accept. + */ fun accept(visitor: FirVisitorVoid) = accept(visitor, null) /** @@ -54,6 +59,15 @@ interface FirElement { */ fun acceptChildren(visitor: FirVisitor, data: D) + /** + * Runs the provided [visitor] on subtrees with roots in this node's children. + * + * Basically, calls `accept(visitor)` on each child of this node. + * + * Does **not** run [visitor] on this node itself. + * + * @param visitor The visitor for children to accept. + */ fun acceptChildren(visitor: FirVisitorVoid) = acceptChildren(visitor, null) /** diff --git a/compiler/fir/tree/tree-generator/src/org/jetbrains/kotlin/fir/tree/generator/printer/ElementPrinter.kt b/compiler/fir/tree/tree-generator/src/org/jetbrains/kotlin/fir/tree/generator/printer/ElementPrinter.kt index 1686e500899..d81f69bc432 100644 --- a/compiler/fir/tree/tree-generator/src/org/jetbrains/kotlin/fir/tree/generator/printer/ElementPrinter.kt +++ b/compiler/fir/tree/tree-generator/src/org/jetbrains/kotlin/fir/tree/generator/printer/ElementPrinter.kt @@ -21,14 +21,15 @@ internal class ElementPrinter(printer: SmartPrinter) : AbstractElementPrinter Unit) { private val dataTP = TypeVariable("D") private val dataParameter = FunctionParameter("data", dataTP) +private fun acceptMethodKDoc( + visitorParameter: FunctionParameter, + dataParameter: FunctionParameter?, + returnType: TypeRef, + treeName: String, +) = buildString { + append("Runs the provided [") + append(visitorParameter.name) + append("] on the ") + append(treeName) + append(" subtree with the root at this node.\n\n") + append("@param ") + append(visitorParameter.name) + append(" The visitor to accept.") + if (dataParameter != null) { + append("\n@param ") + append(dataParameter.name) + append(" An arbitrary context to pass to each invocation of [") + append(visitorParameter.name) + append("]'s methods.") + } + if (returnType != StandardTypes.unit) { + append("\n@return The value returned by the topmost `visit*` invocation.") + } +} + context(ImportCollector) fun SmartPrinter.printAcceptMethod( element: AbstractElement<*, *, *>, @@ -211,15 +237,7 @@ fun SmartPrinter.printAcceptMethod( 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() - ) + printKDoc(acceptMethodKDoc(visitorParameter, dataParameter, resultTP, treeName)) } printFunctionDeclaration( name = "accept", @@ -291,6 +309,32 @@ fun SmartPrinter.printTransformMethod( println() } +private fun acceptChildrenKDoc(visitorParameter: FunctionParameter, dataParameter: FunctionParameter?) = buildString { + append("Runs the provided [") + append(visitorParameter.name) + append("] on subtrees with roots in this node's children.\n\n") + append("Basically, calls `accept(") + append(visitorParameter.name) + if (dataParameter != null) { + append(", ") + append(dataParameter.name) + } + append(")` on each child of this node.\n\n") + append("Does **not** run [") + append(visitorParameter.name) + append("] on this node itself.\n\n") + append("@param ") + append(visitorParameter.name) + append(" The visitor for children to accept.") + if (dataParameter != null) { + append("\n@param ") + append(dataParameter.name) + append(" An arbitrary context to pass to each invocation of [") + append(visitorParameter.name) + append("]'s methods.") + } +} + context(ImportCollector) fun SmartPrinter.printAcceptChildrenMethod( element: FieldContainer<*>, @@ -303,18 +347,7 @@ fun SmartPrinter.printAcceptChildrenMethod( println() 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() - ) + printKDoc(acceptChildrenKDoc(visitorParameter, dataParameter)) } printFunctionDeclaration( name = "acceptChildren", @@ -381,15 +414,18 @@ fun SmartPrinter.printTransformChildrenMethod( } context(ImportCollector) -fun SmartPrinter.printAcceptVoidMethod(visitorType: ClassRef<*>) { +fun SmartPrinter.printAcceptVoidMethod(visitorType: ClassRef<*>, treeName: String) { val visitorParameter = FunctionParameter("visitor", visitorType) - printFunctionDeclaration("accept", listOf(visitorParameter), StandardTypes.unit) + val returnType = StandardTypes.unit + printKDoc(acceptMethodKDoc(visitorParameter, null, returnType, treeName)) + printFunctionDeclaration("accept", listOf(visitorParameter), returnType) println(" = accept(", visitorParameter.name, ", null)") } context(ImportCollector) fun SmartPrinter.printAcceptChildrenVoidMethod(visitorType: ClassRef<*>) { val visitorParameter = FunctionParameter("visitor", visitorType) + printKDoc(acceptChildrenKDoc(visitorParameter, null)) printFunctionDeclaration("acceptChildren", listOf(visitorParameter), StandardTypes.unit) println(" = acceptChildren(", visitorParameter.name, ", null)") } diff --git a/native/swift/sir/gen/org/jetbrains/kotlin/sir/SirElement.kt b/native/swift/sir/gen/org/jetbrains/kotlin/sir/SirElement.kt index 62c2cd44631..3f35eeb6b44 100644 --- a/native/swift/sir/gen/org/jetbrains/kotlin/sir/SirElement.kt +++ b/native/swift/sir/gen/org/jetbrains/kotlin/sir/SirElement.kt @@ -39,6 +39,11 @@ sealed interface SirElement { fun transform(transformer: SirTransformer, data: D): E = transformer.transformElement(this, data) as E + /** + * Runs the provided [visitor] on the Swift IR subtree with the root at this node. + * + * @param visitor The visitor to accept. + */ fun accept(visitor: SirVisitorVoid) = accept(visitor, null) /** @@ -53,6 +58,15 @@ sealed interface SirElement { */ fun acceptChildren(visitor: SirVisitor, data: D) + /** + * Runs the provided [visitor] on subtrees with roots in this node's children. + * + * Basically, calls `accept(visitor)` on each child of this node. + * + * Does **not** run [visitor] on this node itself. + * + * @param visitor The visitor for children to accept. + */ fun acceptChildren(visitor: SirVisitorVoid) = acceptChildren(visitor, null) /** diff --git a/native/swift/sir/tree-generator/src/org/jetbrains/kotlin/sir/tree/generator/printer/ElementPrinter.kt b/native/swift/sir/tree-generator/src/org/jetbrains/kotlin/sir/tree/generator/printer/ElementPrinter.kt index 84790311c3f..03c0bc502df 100644 --- a/native/swift/sir/tree-generator/src/org/jetbrains/kotlin/sir/tree/generator/printer/ElementPrinter.kt +++ b/native/swift/sir/tree-generator/src/org/jetbrains/kotlin/sir/tree/generator/printer/ElementPrinter.kt @@ -34,7 +34,7 @@ internal class ElementPrinter(printer: SmartPrinter) : AbstractElementPrinter