Add KDoc to ObsoleteDescriptorBasedAPI

compiler/ir/ir.tree/src/org/jetbrains/kotlin/ir/ObsoleteDescriptorBasedAPI.kt

@@ -5,5 +5,13 @@
 
 package org.jetbrains.kotlin.ir
 
+/**
+ * This annotation is used on IR API elements which use front-end (FE) descriptors to obtain information, directly or indirectly.
+ *
+ * Descriptors are used in FE to represent main declaration properties and to refer declarations.
+ * Early IR versions were descriptor-based, so IR elements used descriptors to obtain some information about element properties.
+ * However, more correct and universal way is to store all necessary information inside IR elements themselves
+ * and do not use descriptors as some intermediate storage. It's planned to remove all descriptor usages from IR in future.
+ */
 @RequiresOptIn(message = "Please use IR declaration properties and not its descriptor properties", level = RequiresOptIn.Level.ERROR)
 annotation class ObsoleteDescriptorBasedAPI