[SIR, FIR generators] Add KDocs for visitor-related methods of elements

compiler/fir/tree/gen/org/jetbrains/kotlin/fir/FirElement.kt

@@ -40,6 +40,11 @@ interface FirElement {
     fun <E : FirElement, D> transform(transformer: FirTransformer<D>, 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 <R, D> acceptChildren(visitor: FirVisitor<R, D>, 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)
 
     /**

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<El
     override fun SmartPrinter.printAdditionalMethods(element: Element) {
         val kind = element.kind ?: error("Expected non-null element kind")
         with(element) {
-            printAcceptMethod(element, firVisitorType, hasImplementation = true, treeName = "FIR")
+            val treeName = "FIR"
+            printAcceptMethod(element, firVisitorType, hasImplementation = true, treeName = treeName)
 
             printTransformMethod(
                 element = element,
                 transformerClass = firTransformerType,
                 implementation = "transformer.transform${element.name}(this, data)",
                 returnType = TypeVariable("E", listOf(AbstractFirTreeBuilder.baseFirElement)),
-                treeName = "FIR",
+                treeName = treeName,
             )
 
             fun Field.replaceDeclaration(override: Boolean, overridenType: TypeRefWithNullability? = null, forceNullable: Boolean = false) {
@@ -66,7 +67,7 @@ internal class ElementPrinter(printer: SmartPrinter) : AbstractElementPrinter<El
 
             if (element.isRootElement) {
                 println()
-                printAcceptVoidMethod(firVisitorVoidType)
+                printAcceptVoidMethod(firVisitorVoidType, treeName)
                 printAcceptChildrenMethod(
                     element = element,
                     visitorClass = firVisitorType,

generators/tree-generator-common/src/org/jetbrains/kotlin/generators/tree/printer/printUtils.kt

@@ -199,6 +199,32 @@ inline fun SmartPrinter.printBlock(body: () -> 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(
+        printKDoc(acceptMethodKDoc(visitorParameter, dataParameter, resultTP, treeName))
-            """
-            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",
@@ -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(
+        printKDoc(acceptChildrenKDoc(visitorParameter, dataParameter))
-            """
-            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",
@@ -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)")
 }

native/swift/sir/gen/org/jetbrains/kotlin/sir/SirElement.kt

@@ -39,6 +39,11 @@ sealed interface SirElement {
     fun <E : SirElement, D> transform(transformer: SirTransformer<D>, 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 <R, D> acceptChildren(visitor: SirVisitor<R, D>, 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)
 
     /**

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<El
 
         if (element.isRootElement) {
             println()
-            printAcceptVoidMethod(elementVisitorVoidType)
+            printAcceptVoidMethod(elementVisitorVoidType, treeName)
             printAcceptChildrenMethod(element, elementVisitorType, TypeVariable("R"))
             println()
             println()