Kotlin: getFunctionLabel: Add comments

igfoo · igfoo · commit 8d2221ea608f · 2022-05-10T19:51:14.000+01:00
diff --git a/java/kotlin-extractor/src/main/kotlin/KotlinUsesExtractor.kt b/java/kotlin-extractor/src/main/kotlin/KotlinUsesExtractor.kt
@@ -634,21 +634,53 @@ class X {
             else -> null
         }
 
+    /*
+     * This is the normal getFunctionLabel function to use. If you want
+     * to refer to the function in its source class then
+     * classTypeArgsIncludingOuterClasses should be null. Otherwise, it
+     * is the list of type arguments that need to be applied to its
+     * enclosing classes to get the instantiation that this function is
+     * in.
+     */
     fun getFunctionLabel(f: IrFunction, classTypeArgsIncludingOuterClasses: List<IrTypeArgument>?) : String {
         return getFunctionLabel(f, null, classTypeArgsIncludingOuterClasses)
     }
 
-    fun getFunctionLabel(f: IrFunction, parentId: Label<out DbElement>?, classTypeArgsIncludingOuterClasses: List<IrTypeArgument>?) =
-        getFunctionLabel(f.parent, parentId, getFunctionShortName(f), f.valueParameters, f.returnType, f.extensionReceiverParameter, getFunctionTypeParameters(f), classTypeArgsIncludingOuterClasses)
-
+    /*
+     * There are some pairs of classes (e.g. `kotlin.Throwable` and
+     * `java.lang.Throwable`) which are really just 2 different names
+     * for the same class. However, we extract them as separate
+     * classes. When extracting `kotlin.Throwable`'s methods, if we
+     * looked up the parent ID ourselves, we would get as ID for
+     * `java.lang.Throwable`, which isn't what we want. So we have to
+     * allow it to be passed in.
+    */
+    fun getFunctionLabel(f: IrFunction, maybeParentId: Label<out DbElement>?, classTypeArgsIncludingOuterClasses: List<IrTypeArgument>?) =
+        getFunctionLabel(f.parent, maybeParentId, getFunctionShortName(f), f.valueParameters, f.returnType, f.extensionReceiverParameter, getFunctionTypeParameters(f), classTypeArgsIncludingOuterClasses)
+
+    /*
+     * This function actually generates the label for a function.
+     * Sometimes, a function is only generated by kotlinc when writing a
+     * class file, so there is no corresponding `IrFunction` for it.
+     * This function therefore takes all the constituent parts of a
+     * function instead.
+     */
     fun getFunctionLabel(
+        // The parent of the function; normally f.parent.
         parent: IrDeclarationParent,
+        // The ID of the function's parent, or null if we should work it out ourselves.
         maybeParentId: Label<out DbElement>?,
+        // The name of the function; normally f.name.asString().
         name: String,
+        // The value parameters that the functions takes; normally f.valueParameters.
         parameters: List<IrValueParameter>,
+        // The return type of the function; normally f.returnType.
         returnType: IrType,
+        // The extension receiver of the function, if any; normally f.extensionReceiverParameter.
         extensionReceiverParameter: IrValueParameter?,
+        // The type parameters of the function. This does not include type parameters of enclosing classes.
         functionTypeParameters: List<IrTypeParameter>,
+        // The type arguments of enclosing classes of the function.
         classTypeArgsIncludingOuterClasses: List<IrTypeArgument>?
     ): String {
         val parentId = maybeParentId ?: useDeclarationParent(parent, false, classTypeArgsIncludingOuterClasses, true)
