From 4506ca6792001bdc2bfb4153a8662c5e2e4aab08 Mon Sep 17 00:00:00 2001
From: Ivan Kylchik <ivan.kylchik@jetbrains.com>
Date: Wed, 21 Dec 2022 19:18:07 +0100
Subject: [PATCH] Add KDoc to `IrAttributeContainer`

---
 .../kotlin/ir/declarations/IrAttributeContainer.kt     |  8 +++++++-
 .../src/org/jetbrains/kotlin/ir/generator/IrTree.kt    | 10 ++++++++++
 .../kotlin/ir/generator/config/ConfigModel.kt          |  1 +
 .../org/jetbrains/kotlin/ir/generator/model/Model.kt   |  1 +
 .../jetbrains/kotlin/ir/generator/print/Elements.kt    | 10 +++++++---
 5 files changed, 26 insertions(+), 4 deletions(-)

diff --git a/compiler/ir/ir.tree/gen/org/jetbrains/kotlin/ir/declarations/IrAttributeContainer.kt b/compiler/ir/ir.tree/gen/org/jetbrains/kotlin/ir/declarations/IrAttributeContainer.kt
index b1508c03515..6c755777b00 100644
--- a/compiler/ir/ir.tree/gen/org/jetbrains/kotlin/ir/declarations/IrAttributeContainer.kt
+++ b/compiler/ir/ir.tree/gen/org/jetbrains/kotlin/ir/declarations/IrAttributeContainer.kt
@@ -11,7 +11,13 @@ package org.jetbrains.kotlin.ir.declarations
 import org.jetbrains.kotlin.ir.IrElement
 
 /**
- * A non-leaf IR tree element.
+ * Represents an IR element that can be copied, but must remember its original element. It is
+ * useful, for example, to keep track of generated names for anonymous declarations.
+ * @property attributeOwnerId original element before copying. Always satisfies the following
+ *   invariant: this.attributeOwnerId == this.attributeOwnerId.attributeOwnerId.
+ * @property attributeOwnerIdBeforeInline original element before inlining. Useful only with IR
+ *   inliner. null if the element wasn't inlined. Unlike [attributeOwnerId], doesn't have the
+ *   idempotence invariant and can contain a chain of declarations.
  * @sample org.jetbrains.kotlin.ir.generator.IrTree.attributeContainer
  */
 interface IrAttributeContainer : IrElement {
diff --git a/compiler/ir/ir.tree/tree-generator/src/org/jetbrains/kotlin/ir/generator/IrTree.kt b/compiler/ir/ir.tree/tree-generator/src/org/jetbrains/kotlin/ir/generator/IrTree.kt
index 53e4455f60c..04a3e1313c2 100644
--- a/compiler/ir/ir.tree/tree-generator/src/org/jetbrains/kotlin/ir/generator/IrTree.kt
+++ b/compiler/ir/ir.tree/tree-generator/src/org/jetbrains/kotlin/ir/generator/IrTree.kt
@@ -170,6 +170,16 @@ object IrTree : AbstractTreeBuilder() {
         +listField("sealedSubclasses", classSymbolType, mutability = Var)
     }
     val attributeContainer: ElementConfig by element(Declaration) {
+        kDoc = """
+            Represents an IR element that can be copied, but must remember its original element. It is
+            useful, for example, to keep track of generated names for anonymous declarations.
+            @property attributeOwnerId original element before copying. Always satisfies the following
+              invariant: `this.attributeOwnerId == this.attributeOwnerId.attributeOwnerId`.
+            @property attributeOwnerIdBeforeInline original element before inlining. Useful only with IR
+              inliner. `null` if the element wasn't inlined. Unlike [attributeOwnerId], doesn't have the
+              idempotence invariant and can contain a chain of declarations.
+        """.trimIndent()
+
         +field("attributeOwnerId", attributeContainer)
         +field("attributeOwnerIdBeforeInline", attributeContainer, nullable = true) // null <=> this element wasn't inlined
     }
diff --git a/compiler/ir/ir.tree/tree-generator/src/org/jetbrains/kotlin/ir/generator/config/ConfigModel.kt b/compiler/ir/ir.tree/tree-generator/src/org/jetbrains/kotlin/ir/generator/config/ConfigModel.kt
index 77e7e4d1ad8..2d52e01b37b 100644
--- a/compiler/ir/ir.tree/tree-generator/src/org/jetbrains/kotlin/ir/generator/config/ConfigModel.kt
+++ b/compiler/ir/ir.tree/tree-generator/src/org/jetbrains/kotlin/ir/generator/config/ConfigModel.kt
@@ -40,6 +40,7 @@ class ElementConfig(
 
     var generationCallback: (TypeSpec.Builder.() -> Unit)? = null
     var suppressPrint = false
+    var kDoc: String? = null
 
     override val element get() = this
     override val args get() = emptyMap<NamedTypeParameterRef, TypeRef>()
diff --git a/compiler/ir/ir.tree/tree-generator/src/org/jetbrains/kotlin/ir/generator/model/Model.kt b/compiler/ir/ir.tree/tree-generator/src/org/jetbrains/kotlin/ir/generator/model/Model.kt
index 991e63f39af..339d86a205a 100644
--- a/compiler/ir/ir.tree/tree-generator/src/org/jetbrains/kotlin/ir/generator/model/Model.kt
+++ b/compiler/ir/ir.tree/tree-generator/src/org/jetbrains/kotlin/ir/generator/model/Model.kt
@@ -42,6 +42,7 @@ class Element(
     val generationCallback = config.generationCallback
     val suppressPrint = config.suppressPrint
     val propertyName = config.propertyName
+    val kDoc = config.kDoc
 
     override fun toString() = name
 
diff --git a/compiler/ir/ir.tree/tree-generator/src/org/jetbrains/kotlin/ir/generator/print/Elements.kt b/compiler/ir/ir.tree/tree-generator/src/org/jetbrains/kotlin/ir/generator/print/Elements.kt
index 609ba3b0e03..7ce750f7b9c 100644
--- a/compiler/ir/ir.tree/tree-generator/src/org/jetbrains/kotlin/ir/generator/print/Elements.kt
+++ b/compiler/ir/ir.tree/tree-generator/src/org/jetbrains/kotlin/ir/generator/print/Elements.kt
@@ -180,9 +180,13 @@ fun printElements(generationPath: File, model: Model) = sequence {
 
 private fun TypeSpec.Builder.generateElementKDoc(element: Element) {
     addKdoc(buildString {
-        append("A ")
-        append(if (element.isLeaf) "leaf" else "non-leaf")
-        appendLine(" IR tree element.")
+        if (element.kDoc != null) {
+            appendLine(element.kDoc)
+        } else {
+            append("A ")
+            append(if (element.isLeaf) "leaf" else "non-leaf")
+            appendLine(" IR tree element.")
+        }
 
         append("@sample ${element.propertyName}")
     })