Document and cleanup how we import unsigned swift types

Author: ktoso

Samples/SwiftKitSampleApp/Sources/MySwiftLibrary/MySwiftClass.swift

@@ -61,6 +61,10 @@ public class MySwiftClass {
     return Int.random(in: 1..<256)
   }
 
+  public func takeUnsignedShort(arg: UInt16) {
+    p("\(UInt32.self) = \(arg)")
+  }
+
   public func takeUnsignedInt(arg: UInt32) {
     p("\(UInt32.self) = \(arg)")
   }

Sources/JExtractSwiftLib/JavaTypes/JavaType+SwiftKit.swift

@@ -30,11 +30,7 @@ extension JavaType {
       }
 
     case "Int16": self = .short
-    case "UInt16":
-    self = switch unsigned {
-      case .ignoreSign: .short
-      case .wrapAsUnsignedNumbers: JavaType.swiftkit.primitives.UnsignedShort
-      }
+    case "UInt16": self = .char
 
     case "Int32": self = .int
     case "UInt32":
@@ -77,14 +73,13 @@ extension JavaType {
   enum swiftkit {
     enum primitives {
       static let package = "org.swift.swiftkit.core.primitives"
-      static var UnsignedShort: JavaType {
-        .class(package: primitives.package, name: "UnsignedShort")
-      }
 
       static var UnsignedByte: JavaType {
         .class(package: primitives.package, name: "UnsignedByte")
       }
 
+      // UnsignedShort is not necessary because UInt16 is directly expressible as Java's unsigned 'char'.
+
       static var UnsignedInteger: JavaType {
         .class(package: primitives.package, name: "UnsignedInteger")
       }

Sources/JavaTypes/JavaType+SwiftNames.swift

@@ -87,6 +87,26 @@ extension JavaType {
 
 }
 
+/// Determines how type conversion should deal with Swift's unsigned numeric types.
+///
+/// When `ignoreSign` is used, unsigned Swift types are imported directly as their corresponding bit-width types,
+/// which may yield surprising values when an unsigned Swift value is interpreted as a signed Java type:
+/// - `UInt8` is imported as `byte`
+/// - `UInt16` is imported as `char` (this is always correct, since `char` is unsigned in Java)
+/// - `UInt32` is imported as `int`
+/// - `UInt64` is imported as `long`
+///
+/// When `wrapAsUnsignedNumbers` is used, unsigned Swift types are imported as safe "wrapper" types on the Java side.
+/// These make the Unsigned nature of the types explicit in Java, however they come at a cost of allocating the wrapper
+/// object, and indirection when accessing the underlying numeric value. These are often useful as a signal to watch out
+/// when dealing with a specific API, however in high performance use-cases, one may want to choose using the primitive
+///  values directly, and interact with them using {@code UnsignedIntegers} SwiftKit helper classes on the Java side.
+///
+/// The type mappings in this mode are as follows:
+/// - `UInt8` is imported as `org.swift.swiftkit.core.primitives.UnsignedByte`
+/// - `UInt16` is imported as `char` (this is always correct, since `char` is unsigned in Java)
+/// - `UInt32` is imported as `org.swift.swiftkit.core.primitives.UnsignedInteger`
+/// - `UInt64` is imported as `org.swift.swiftkit.core.primitives.UnsignedLong`
 public enum UnsignedNumericsMode {
   case ignoreSign
   case wrapAsUnsignedNumbers