From 10aa5fc7ef939811cccfe2124ec7172344de268a Mon Sep 17 00:00:00 2001
From: Sergej Jaskiewicz <sergej.jaskiewicz@jetbrains.com>
Date: Thu, 22 Jun 2023 13:41:33 +0200
Subject: [PATCH] [mangling] Add kdocs to some `KotlinMangler` methods

---
 .../jetbrains/kotlin/ir/util/KotlinMangler.kt | 58 +++++++++++++++++++
 1 file changed, 58 insertions(+)

diff --git a/compiler/ir/ir.tree/src/org/jetbrains/kotlin/ir/util/KotlinMangler.kt b/compiler/ir/ir.tree/src/org/jetbrains/kotlin/ir/util/KotlinMangler.kt
index d5d66036283..ceffaf521a9 100644
--- a/compiler/ir/ir.tree/src/org/jetbrains/kotlin/ir/util/KotlinMangler.kt
+++ b/compiler/ir/ir.tree/src/org/jetbrains/kotlin/ir/util/KotlinMangler.kt
@@ -15,10 +15,68 @@ interface KotlinMangler<D : Any> {
     val String.hashMangle: Long
 
     fun D.isExported(compatibleMode: Boolean): Boolean
+
+    /**
+     * Returns the mangled name for the declaration [D], prefixed by mangled names of all its parents.
+     *
+     * For example, for `foo`'s getter in the following code:
+     * ```kotlin
+     * class Test {
+     *     val foo: Int
+     * }
+     * ```
+     * the result of this function will be `"Test#<get-foo>(){}kotlin.Int"` or `"Test#<get-foo>(){}"` (depending on the target platform).
+     *
+     * The result of this function is only used for assigning names to binary symbols of Kotlin functions in the final executable produced
+     * by Kotlin/Native, and for generating stable names in the JavaScript code produced by Kotlin/JS. **It does not affect klib ABI.**
+     *
+     * @param compatibleMode If `true`, the mangled names of property backing fields are just those fields' names.
+     * Otherwise, mangles such fields exactly as their corresponding properties.
+     */
     fun D.mangleString(compatibleMode: Boolean): String
+
+    /**
+     * Returns the mangled name for the declaration [D] to be used for computing that declaration's [IdSignature].
+     *
+     * Unlike the one computed by [mangleString], this mangled name does not include mangled names of the declaration's parents.
+     *
+     * For example, for `foo`'s getter in the following code:
+     * ```kotlin
+     * class Test {
+     *     val foo: Int
+     * }
+     * ```
+     * the result of this function will be `"<get-foo>(){}kotlin.Int"` or `"<get-foo>(){}"` (depending on the target platform).
+     *
+     * **The result of this function affects klib ABI.**
+     *
+     * @param compatibleMode If `true`, the mangled names of property backing fields are just those fields' names.
+     * Otherwise, mangles such fields exactly as their corresponding properties.
+     */
     fun D.signatureString(compatibleMode: Boolean): String
 
+    /**
+     * Computes the hash code of the string returned by [mangleString] using the CityHash64 algorithm.
+     *
+     * **The result of this function does not affect klib ABI.**
+     *
+     * @param compatibleMode If `true`, the mangled names of property backing fields are just those fields' names.
+     * Otherwise, mangles such fields exactly as their corresponding properties.
+     */
     fun D.hashedMangle(compatibleMode: Boolean): Long = mangleString(compatibleMode).hashMangle
+
+    /**
+     * Computes the hash code of the string returned by [signatureString] using the CityHash64 algorithm.
+     *
+     * This hash code is to be used for building the declaration's [IdSignature].
+     *
+     * **The result of this function affects klib ABI.**
+     *
+     * @param compatibleMode If `true`, the mangled names of property backing fields are just those fields' names.
+     * Otherwise, mangles such fields exactly as their corresponding properties.
+     *
+     * @see [IdSignature.CommonSignature.id]
+     */
     fun D.signatureMangle(compatibleMode: Boolean): Long = signatureString(compatibleMode).hashMangle
 
     fun D.isPlatformSpecificExport(): Boolean = false