Kotlin: minimize the usage of 'JvmSuppressWildcards' (#1793)

---------- Motivation ----------
The annotation mentioned in the title of the commit was used
for parameter types of collections (List, Map, Set) to avoid
interoperability problems when the generated code is accessed
from Java.

The problematic case is checked in KotlinInteropTest.java.

However, it turns out that the mentioned annotation needs to be
only used for enums and open types, because if the type is final
then wildcard is not generated.

---------- Solution ----------
KotlinNameResolver class is adjusted to generate the annotation for
parameter type of collection only when it is enum or the type is open.

Smoke tests are adjusted to showcase that this change minimizes the
usage of 'JvmSuppressWildcards' annotation.

The functional test called 'KotlinInteropTest.java' passes without problems after the change.

Signed-off-by: Patryk Wrobel <183546751+pwrobeldev@users.noreply.github.com>

Author: pwrobeldev

CHANGELOG.md

@@ -4,6 +4,7 @@
  * Kotlin: use `@JvmSynthetic` annotation for Kotlin internal elements whenever possible to hide them from Java code.
  * Kotlin: allow the usage of 'RequiresOptIn' and 'OptIn' annotations for internal API via CLI parameters. This way error is generated when the code, which is not intended to access the internal API uses it. Three new CLI parameters are available: 'androidrequiresoptinannotation', 'androidoptinannotation' and 'androidinternalapiannotationname'.
  * Kotlin: for external types usage in Kotlin, use 'internal' keyword for the types, which are generated by Gluecodium as their 'internal' representation.
+ * Kotlin: minimize the usage of 'JvmSuppressWildcards' annotation for collection parameters. This annotation was used for all generated collection types. It needs to be used only when collection type holds enumeration or open type e.g.: 'open class', 'interface' or 'fun interface'.
 
 ## 14.0.0
 Release date 2025-12-01

functional-tests/functional/android/src/test/java/com/here/android/test/KotlinInteropTest.java

@@ -32,21 +32,61 @@
 @RunWith(RobolectricTestRunner.class)
 @Config(sdk = Build.VERSION_CODES.M, application = RobolectricApplication.class)
 public class KotlinInteropTest {
-  private int someJavaFunctionThatTakesList(List<SomeOpenNumberWrapperClass> someList) {
+  private int someJavaFunctionThatTakesListOfOpenClasses(List<SomeOpenNumberWrapperClass> someList) {
+    return someList.size();
+  }
+
+  private int someJavaFunctionThatTakesListOfInterfaces(List<SomeDummyInterface> someList) {
+    return someList.size();
+  }
+
+  private int someJavaFunctionThatTakesListOfStructs(List<SomeDummyStruct> someList) {
+    return someList.size();
+  }
+
+  private int someJavaFunctionThatTakesListOfFinalClass(List<PlainDataStructures> someList) {
+    return someList.size();
+  }
+
+  private int someJavaFunctionThatTakesListOfEnums(List<SomeDummyEnum> someList) {
     return someList.size();
   }
 
   @Test
   public void javaFunctionWithCollectionParamsCanBeCalledWithOpenClassFields() {
     SomeStructWithCollection someStruct = new SomeStructWithCollection();
-    assertEquals(0, someJavaFunctionThatTakesList(someStruct.openClassList));
+    assertEquals(0, someJavaFunctionThatTakesListOfOpenClasses(someStruct.openClassList));
+  }
+
+  @Test
+  public void javaFunctionWithCollectionParamsCanBeCalledWithInterfaceFields() {
+    SomeStructWithCollection someStruct = new SomeStructWithCollection();
+    assertEquals(0, someJavaFunctionThatTakesListOfInterfaces(someStruct.interfacesList));
+  }
+
+  @Test
+  public void javaFunctionWithCollectionParamsCanBeCalledWithStructFields() {
+    SomeStructWithCollection someStruct = new SomeStructWithCollection();
+    assertEquals(0, someJavaFunctionThatTakesListOfStructs(someStruct.structsList));
+  }
+
+  @Test
+  public void javaFunctionWithCollectionParamsCanBeCalledWithFinalClassFields() {
+    SomeStructWithCollection someStruct = new SomeStructWithCollection();
+    assertEquals(0, someJavaFunctionThatTakesListOfFinalClass(someStruct.finalClassList));
+  }
+
+  @Test
+  public void javaFunctionWithCollectionParamsCanBeCalledWithEnumFields() {
+    SomeStructWithCollection someStruct = new SomeStructWithCollection();
+    assertEquals(0, someJavaFunctionThatTakesListOfEnums(someStruct.enumList));
   }
 
   @Test
   public void whenJavaAccessesStructFieldOfListTypeThenElementsCanBeAdded() {
     SomeStructWithCollection someStruct = new SomeStructWithCollection();
     someStruct.openClassList.add(new SomeOpenNumberWrapperClass(777));
 
-    assertEquals(1, someJavaFunctionThatTakesList(someStruct.openClassList));
+    assertEquals(1, someJavaFunctionThatTakesListOfOpenClasses(someStruct.openClassList));
   }
 }

functional-tests/functional/input/lime/Structs.lime

@@ -119,8 +119,25 @@ open class SomeOpenNumberWrapperClass {
     constructor make(n: Int)
 }
 
+interface SomeDummyInterface {
+    fun getInt(): Int
+}
+
+struct SomeDummyStruct {
+    someInt: Int
+}
+
+enum SomeDummyEnum {
+  FOO,
+  BAR
+}
+
 struct SomeStructWithCollection {
     emptyNumbers: List<Int> = []
     numbers: List<Int> = [1, 2, 3]
     openClassList: List<SomeOpenNumberWrapperClass> = []
+    interfacesList: List<SomeDummyInterface> = []
+    structsList: List<SomeDummyStruct> = []
+    finalClassList: List<PlainDataStructures> = []
+    enumList: List<SomeDummyEnum> = []
 }

gluecodium/src/main/java/com/here/gluecodium/generator/kotlin/KotlinNameResolver.kt

@@ -29,8 +29,10 @@ import com.here.gluecodium.model.lime.LimeAttributeValueType.FUNCTION_NAME
 import com.here.gluecodium.model.lime.LimeBasicType
 import com.here.gluecodium.model.lime.LimeBasicType.TypeId
 import com.here.gluecodium.model.lime.LimeComment
+import com.here.gluecodium.model.lime.LimeContainerWithInheritance
 import com.here.gluecodium.model.lime.LimeDirectTypeRef
 import com.here.gluecodium.model.lime.LimeElement
+import com.here.gluecodium.model.lime.LimeEnumeration
 import com.here.gluecodium.model.lime.LimeExternalDescriptor.Companion.NAME_NAME
 import com.here.gluecodium.model.lime.LimeFunction
 import com.here.gluecodium.model.lime.LimeGenericType
@@ -164,14 +166,29 @@ internal class KotlinNameResolver(
 
     private fun resolveGenericTypeRef(limeType: LimeGenericType) =
         when (limeType) {
-            is LimeList -> "List<@JvmSuppressWildcards ${resolveTypeRef(limeType.elementType)}>"
-            is LimeSet -> "Set<@JvmSuppressWildcards ${resolveTypeRef(limeType.elementType)}>"
-            is LimeMap -> "Map<@JvmSuppressWildcards ${resolveTypeRef(
-                limeType.keyType,
-            )}, @JvmSuppressWildcards ${resolveTypeRef(limeType.valueType)}>"
+            is LimeList -> "List<${resolveContainerParamType(limeType.elementType)}>"
+            is LimeSet -> "Set<${resolveContainerParamType(limeType.elementType)}>"
+            is LimeMap -> "Map<${resolveContainerParamType(limeType.keyType)}, ${resolveContainerParamType(limeType.valueType)}>"
             else -> throw GluecodiumExecutionException("Unsupported element type ${limeType.javaClass.name}")
         }
 
+    private fun resolveContainerParamType(typeRef: LimeTypeRef) =
+        if (needsToSuppressWildcards(typeRef.type)) {
+            "@JvmSuppressWildcards ${resolveTypeRef(typeRef)}"
+        } else {
+            resolveTypeRef(typeRef)
+        }
+
+    // The parameters of generic types (List, Set, Map) must use '@JvmSuppressWildcards'
+    // for 'open' types to avoid compilation problems when accessed from Java code.
+    private fun needsToSuppressWildcards(type: LimeType) =
+        when (type) {
+            is LimeContainerWithInheritance -> type.isOpen
+            is LimeLambda -> true
+            is LimeEnumeration -> true
+            else -> false
+        }
+
     private fun resolveNestedNames(limeElement: LimeNamedElement): List<String> {
         val elementName = kotlinNameRules.getName(limeElement)
         val parentElement = if (limeElement.path.hasParent) getParentElement(limeElement) else null

gluecodium/src/test/resources/smoke/constants/output/android-kotlin/com/example/smoke/CollectionConstants.kt

@@ -5,6 +5,7 @@
 
 @file:JvmName("CollectionConstantsExtensions")
 
+
 package com.example.smoke
 
 import com.example.NativeBase
@@ -29,10 +30,10 @@ class CollectionConstants : NativeBase {
 
 
     companion object {
-        @JvmField final val LIST_CONSTANT: List<@JvmSuppressWildcards String> = mutableListOf("foo", "bar")
-        @JvmField final val SET_CONSTANT: Set<@JvmSuppressWildcards String> = mutableSetOf("foo", "bar")
-        @JvmField final val MAP_CONSTANT: Map<@JvmSuppressWildcards String, @JvmSuppressWildcards String> = mutableMapOf("foo" to "bar")
-        @JvmField final val MIXED_CONSTANT: Map<@JvmSuppressWildcards List<@JvmSuppressWildcards String>, @JvmSuppressWildcards Set<@JvmSuppressWildcards String>> = mutableMapOf(mutableListOf("foo") to mutableSetOf("bar"))
+        @JvmField final val LIST_CONSTANT: List<String> = mutableListOf("foo", "bar")
+        @JvmField final val SET_CONSTANT: Set<String> = mutableSetOf("foo", "bar")
+        @JvmField final val MAP_CONSTANT: Map<String, String> = mutableMapOf("foo" to "bar")
+        @JvmField final val MIXED_CONSTANT: Map<List<String>, Set<String>> = mutableMapOf(mutableListOf("foo") to mutableSetOf("bar"))
         @JvmStatic private external fun disposeNativeHandle(nativeHandle: Long)
     }
 }

gluecodium/src/test/resources/smoke/constructors/output/android-kotlin/com/example/smoke/Constructors.kt

@@ -43,7 +43,7 @@ open class Constructors : NativeBase {
     }
 
 
-    constructor(input: List<@JvmSuppressWildcards Double>) : this(create(input), null as Any?) {
+    constructor(input: List<Double>) : this(create(input), null as Any?) {
         cacheThisInstance();
     }
 
@@ -79,7 +79,7 @@ open class Constructors : NativeBase {
         @Throws(Constructors.ConstructorExplodedException::class)
         @JvmStatic private external fun create(input: String) : Long
 
-        @JvmStatic private external fun create(input: List<@JvmSuppressWildcards Double>) : Long
+        @JvmStatic private external fun create(input: List<Double>) : Long
 
         @JvmStatic private external fun create(input: Long) : Long
     }

gluecodium/src/test/resources/smoke/dates/output/android-kotlin/com/example/smoke/Dates.kt

@@ -5,6 +5,7 @@
 
 @file:JvmName("DatesExtensions")
 
+
 package com.example.smoke
 
 import com.example.NativeBase
@@ -53,7 +54,7 @@ class Dates : NativeBase {
         external get
         external set
 
-    var dateSet: Set<@JvmSuppressWildcards Date>
+    var dateSet: Set<Date>
         external get
         external set
 

gluecodium/src/test/resources/smoke/defaults/output/android-kotlin/com/example/smoke/DefaultValues.kt

@@ -5,6 +5,7 @@
 
 @file:JvmName("DefaultValuesExtensions")
 
+
 package com.example.smoke
 
 import com.example.NativeBase
@@ -85,11 +86,11 @@ class DefaultValues : NativeBase {
     }
 
     class StructWithEmptyDefaults {
-        @JvmField var intsField: List<@JvmSuppressWildcards Int>
-        @JvmField var floatsField: List<@JvmSuppressWildcards Float>
-        @JvmField var mapField: Map<@JvmSuppressWildcards Long, @JvmSuppressWildcards String>
+        @JvmField var intsField: List<Int>
+        @JvmField var floatsField: List<Float>
+        @JvmField var mapField: Map<Long, String>
         @JvmField var structField: DefaultValues.StructWithDefaults
-        @JvmField var setTypeField: Set<@JvmSuppressWildcards String>
+        @JvmField var setTypeField: Set<String>
 
 
 

gluecodium/src/test/resources/smoke/defaults_const/output/android-kotlin/com/example/smoke/EnumCollectionDefaults.kt

@@ -5,6 +5,7 @@
 
 @file:JvmName("EnumCollectionDefaultsExtensions")
 
+
 package com.example.smoke
 
 import com.example.fire.Enum1

gluecodium/src/test/resources/smoke/defaults_const/output/android-kotlin/com/example/smoke/EnumCollectionDefaultsExternal.kt

@@ -5,6 +5,7 @@
 
 @file:JvmName("EnumCollectionDefaultsExternalExtensions")
 
+
 package com.example.smoke
 
 import java.util.EnumSet