[IR] Add kdoc to IrElement.copyAttributes

KT-74331
KT-74295

Author: mcpiroman

compiler/ir/ir.tree/src/org/jetbrains/kotlin/ir/declarations/IrDeclarations.kt

@@ -18,6 +18,19 @@ import org.jetbrains.kotlin.name.Name
 import org.jetbrains.kotlin.name.NameUtils.getPackagePartClassNamePrefix
 import java.io.File
 
+/**
+ * This does two different things:
+ *  1. Copies [IrAttribute]s of element [other] into [this]. Attributes already present on [this] are not removed, attributes present
+ *  overridden on both [this] and [other] will be overridden in [this]. The semantics is therefore the same as [MutableMap.putAll].
+ *  2. Assigns [IrElement.attributeOwnerId] to that of [other].
+ *
+ *  Now, those two operations are not clearly connected to each other, although they have been historically.
+ *  In particular, [IrElement.attributeOwnerId] has lost much of its meaning since, and is _not_ connected to [IrAttribute]s.
+ *  But still, _most likely_ you want to do both at the same time, which is what we do here. It should be investigated closer in KT-74295.
+ *
+ *  @param includeAll if `true`, copy all the attributes present in [other],
+ *  if `false`, only those with [IrAttribute.copyByDefault] == `true`.
+ */
 fun IrElement.copyAttributes(other: IrElement, includeAll: Boolean = false) {
     (this as IrElementBase).copyAttributesFrom(other as IrElementBase, includeAll)
     attributeOwnerId = other.attributeOwnerId