[FIR generator] Write kDocs for accept & transform methods in FirElement

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

@@ -156,18 +156,26 @@ fun SmartPrinter.printAcceptMethod(
     element: AbstractElement<*, *>,
     visitorClass: ClassRef<PositionTypeParameterRef>,
     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<PositionTypeParameterRef>,
     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,