[JVM IR] Use KDoc in JvmSymbols i/o regular comments when possible

compiler/ir/backend.jvm/src/org/jetbrains/kotlin/backend/jvm/JvmSymbols.kt

@@ -24,6 +24,7 @@ import org.jetbrains.kotlin.ir.UNDEFINED_OFFSET
 import org.jetbrains.kotlin.ir.builders.declarations.*
 import org.jetbrains.kotlin.ir.declarations.*
 import org.jetbrains.kotlin.ir.declarations.impl.IrExternalPackageFragmentImpl
+import org.jetbrains.kotlin.ir.expressions.IrRawFunctionReference
 import org.jetbrains.kotlin.ir.expressions.impl.IrConstImpl
 import org.jetbrains.kotlin.ir.expressions.impl.IrConstructorCallImpl
 import org.jetbrains.kotlin.ir.symbols.*
@@ -39,6 +40,7 @@ import org.jetbrains.kotlin.resolve.JVM_INLINE_ANNOTATION_FQ_NAME
 import org.jetbrains.kotlin.resolve.jvm.JvmClassName
 import org.jetbrains.kotlin.storage.LockBasedStorageManager
 import org.jetbrains.kotlin.types.Variance
+import java.lang.invoke.MethodType
 
 class JvmSymbols(
     private val context: JvmBackendContext,
@@ -62,15 +64,19 @@ class JvmSymbols(
 
     private val kotlinInternalPackage: IrPackageFragment = createPackage(FqName("kotlin.internal"))
 
-    // Special package for functions representing dynamic symbols referenced by 'INVOKEDYNAMIC' instruction - e.g.,
+    /**
-    //  'get(Ljava/lang/String;)Ljava/util/function/Supplier;'
+     * A special package for functions representing dynamic symbols referenced by the `INVOKEDYNAMIC` instruction — e.g.,
-    // in
+     *  `get(Ljava/lang/String;)Ljava/util/function/Supplier;`
-    //  INVOKEDYNAMIC get(Ljava/lang/String;)Ljava/util/function/Supplier; [
+     * in
-    //      H_INVOKESTATIC java/lang/invoke/LambdaMetafactory.metafactory(...)Ljava/lang/invoke/CallSite;
+     * ```
-    //      ...
+     * INVOKEDYNAMIC get(Ljava/lang/String;)Ljava/util/function/Supplier; [
-    //  ]
+     *     H_INVOKESTATIC java/lang/invoke/LambdaMetafactory.metafactory(...)Ljava/lang/invoke/CallSite;
-    // Such functions don't exist as methods in the actual bytecode
+     *     ...
-    // (they are expected to be provided at run-time by the corresponding bootstrap method).
+     * ]
+     * ```
+     * Such functions don't exist as methods in the actual bytecode
+     * (they are expected to be provided at run-time by the corresponding bootstrap method).
+     */
     val kotlinJvmInternalInvokeDynamicPackage: IrPackageFragment = createPackage(FqName("kotlin.jvm.internal.invokeDynamic"))
 
     private val generateOptimizedCallableReferenceSuperClasses = context.config.generateOptimizedCallableReferenceSuperClasses
@@ -161,8 +167,10 @@ class JvmSymbols(
         })
     }
 
-    // This function is used only with ir inliner. It is needed to ensure that all local declarations inside lambda will be generated,
+    /**
-    // because after inline these lambdas can be dropped.
+     * This function is used only with the IR inliner. It is needed to ensure that all local declarations inside lambda will be generated,
+     * because after inline these lambdas can be dropped.
+     */
     val singleArgumentInlineFunction: IrSimpleFunctionSymbol =
         intrinsicsClass.functions.single { it.owner.name.asString() == "singleArgumentInlineFunction" }
 
@@ -648,35 +656,41 @@ class JvmSymbols(
     val arrayOfAnyType = irBuiltIns.arrayClass.typeWith(irBuiltIns.anyType)
     val arrayOfAnyNType = irBuiltIns.arrayClass.typeWith(irBuiltIns.anyNType)
 
-    // Intrinsic to represent closure creation using INVOKEDYNAMIC with LambdaMetafactory.{metafactory, altMetafactory}
+    /**
-    // as a bootstrap method.
+     * An intrinsic to represent closure creation using `INVOKEDYNAMIC` with `LambdaMetafactory.{metafactory, altMetafactory}`
-    //      fun <SAM_TYPE> `<jvm-indy-lambda-metafactory>`(
+     * as a bootstrap method.
-    //          samMethodType,
+     * ```kotlin
-    //          implMethodReference,
+     * fun <SAM_TYPE : Any> `<jvm-indy-lambda-metafactory>`(
-    //          instantiatedMethodType,
+     *     samMethodType: Any?,
-    //          vararg extraOverriddenMethodTypes,
+     *     implMethodReference: Any?,
-    //          shouldBeSerializable
+     *     instantiatedMethodType: Any?,
-    //      ): SAM_TYPE
+     *     vararg extraOverriddenMethodTypes: Any,
-    // where:
+     *     shouldBeSerializable: Boolean,
-    //      `SAM_TYPE` is a single abstract method interface, which is implemented by a resulting closure;
+     * ): SAM_TYPE
-    //      `samMethodType` is a method type (signature and return type) of a method to be implemented by a closure;
+     * ```
-    //      `implMethodReference` is an actual implementation method (e.g., method for a lambda function);
+     * where:
-    //      `instantiatedMethodType` is a specialized implementation method type;
+     * - `SAM_TYPE` is a single abstract method interface, which is implemented by a resulting closure;
-    //      `extraOverriddenMethodTypes` is a possibly empty vararg of additional methods to be implemented by a closure;
+     * - `samMethodType` is a method type (signature and return type) of a method to be implemented by a closure;
-    //      `shouldBeSerializable` is true if the class of the resulting object should implement `java.io.Serializable`.
+     * - `implMethodReference` is an actual implementation method (e.g., method for a lambda function);
-    //
+     * - `instantiatedMethodType` is a specialized implementation method type;
-    // At this stage, "method types" are represented as IrRawFunctionReference nodes for the functions with corresponding signature.
+     * - `extraOverriddenMethodTypes` is a possibly empty vararg of additional methods to be implemented by a closure;
-    // `<jvm-indy-lambda-metafactory>` call rewriting selects a particular bootstrap method (`metafactory` or `altMetafactory`)
+     * - `shouldBeSerializable` is true if the class of the resulting object should implement `java.io.Serializable`.
-    // and takes care about low-level detains of bootstrap method arguments representation.
+     *
-    // Note that `instantiatedMethodType` is a raw function reference to a "fake" specialized function (belonging to a "fake" specialized
+     * At this stage, "method types" are represented as [IrRawFunctionReference] nodes for the functions with corresponding signature.
-    // class) that doesn't exist in the bytecode and serves only the purpose of representing a corresponding method signature.
+     * `<jvm-indy-lambda-metafactory>` call rewriting selects a particular bootstrap method (`metafactory` or `altMetafactory`)
-    //
+     * and takes care about low-level detains of bootstrap method arguments representation.
-    // Resulting closure produced by INVOKEDYNAMIC instruction has (approximately) the following shape:
+     * Note that `instantiatedMethodType` is a raw function reference to a "fake" specialized function (belonging to a "fake" specialized
-    //      object : ${SAM_TYPE} {
+     * class) that doesn't exist in the bytecode and serves only the purpose of representing a corresponding method signature.
-    //          override fun ${samMethodName}(${instantiatedMethodType}) = ${implMethod}(...)
+     *
-    //          // bridge fun ${samMethodName}(${bridgeMethodType}) = ${instantiatedMethod}(...)
+     * Resulting closure produced by INVOKEDYNAMIC instruction has (approximately) the following shape:
-    //          //      for each 'bridgeMethodType' in [ ${samMethodType}, *${extraOverriddenMethodTypes} ]
+     * ```kotlin
-    //      }
+     *      object : ${SAM_TYPE} {
+     *          override fun ${samMethodName}(${instantiatedMethodType}) = ${implMethod}(...)
+     *          // bridge fun ${samMethodName}(${bridgeMethodType}) = ${instantiatedMethod}(...)
+     *          //      for each 'bridgeMethodType' in [ ${samMethodType}, *${extraOverriddenMethodTypes} ]
+     *      }
+     * ```
+     */
     val indyLambdaMetafactoryIntrinsic: IrSimpleFunctionSymbol =
         irFactory.buildFun {
             name = Name.special("<jvm-indy-lambda-metafactory>")
@@ -753,13 +767,18 @@ class JvmSymbols(
             addValueParameter("isInterface", irBuiltIns.booleanType)
         }.symbol
 
-    // Intrinsic to represent INVOKEDYNAMIC calls in IR.
+    /**
-    //  fun <T> `<jvm-indy>`(
+     * An intrinsic to represent `INVOKEDYNAMIC` calls in IR.
-    //      dynamicCall: T,
+     *
-    //      bootstrapMethodHandle: Any,
+     * ```kotlin
-    //      vararg bootstrapMethodArgs: Any
+     * fun <T> `<jvm-indy>`(
-    //  ): T
+     *     dynamicCall: T,
-    // Bootstrap method handle is represented as a `<jvm-method-handle>` call.
+     *     bootstrapMethodHandle: Any,
+     *     vararg bootstrapMethodArgs: Any
+     * ): T
+     * ```
+     * Bootstrap method handle is represented as a `<jvm-method-handle>` call.
+     */
     val jvmIndyIntrinsic: IrSimpleFunctionSymbol =
         irFactory.buildFun {
             name = Name.special("<jvm-indy>")
@@ -777,9 +796,14 @@ class JvmSymbols(
             returnType = t.defaultType
         }.symbol
 
-    // Intrinsic used to represent MethodType objects in bootstrap method arguments (see jvmInvokeDynamicIntrinsic above).
+    /**
-    // Value argument is a raw function reference to a corresponding method (e.g., 'java.lang.function.Supplier#get').
+     * An intrinsic used to represent [MethodType] objects in bootstrap method arguments (see [jvmIndyIntrinsic] above).
-    // Resulting method type is unsubstituted.
+     * The value argument is a raw function reference to the corresponding method (e.g., `java.lang.function.Supplier#get`).
+     * The resulting method type is unsubstituted.
+     * ```kotlin
+     * fun `<jvm-original-method-type>`(method: Any): Any
+     * ```
+     */
     val jvmOriginalMethodTypeIntrinsic: IrSimpleFunctionSymbol =
         irFactory.buildFun {
             name = Name.special("<jvm-original-method-type>")