introduce some initial docc files

.github/workflows/pull_request.yml

@@ -13,6 +13,30 @@ jobs:
       # FIXME: Something is off with the format task and it gets "stuck", need to investigate
       format_check_enabled: false
       license_header_check_project_name: Swift.org
+      # We need JAVA_HOME to be set to build the Swift project, so the default check would not do that.
+      docs_check_enabled: false
+
+  soundness-docs:
+    name: Soundness (Documentation) (swift:${{ matrix.swift_version }} jdk:${{matrix.jdk_vendor}} os:${{ matrix.os_version }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: true
+      matrix:
+        # swift_version: ['nightly-main']
+        swift_version: ['6.0.2']
+        os_version: ['jammy']
+        jdk_vendor: ['Corretto']
+    container:
+      image: ${{ (contains(matrix.swift_version, 'nightly') && 'swiftlang/swift') || 'swift' }}:${{ matrix.swift_version }}-${{ matrix.os_version }}
+    env:
+      JAVA_HOME: "/usr/lib/jvm/default-jdk"
+    steps:
+      - uses: actions/checkout@v4
+      - name: Prepare CI Environment
+        uses: ./.github/actions/prepare_env
+      - name: "Soundness (Documentation)"
+        run: apt-get -qq update && apt-get -qq -y install curl yq && \
+             curl -s https://raw.githubusercontent.com/swiftlang/github-workflows/refs/heads/main/.github/workflows/scripts/check-docs.sh | bash
 
   test-java:
     name: Java tests (swift:${{ matrix.swift_version }} jdk:${{matrix.jdk_vendor}} os:${{ matrix.os_version }})

.spi.yml

@@ -0,0 +1,9 @@
+version: 1
+builder:
+  configs:
+    - documentation_targets: [
+      SwiftJava,
+      JavaKit,
+      SwiftKitSwift,
+      JExtractSwift
+    ]

Package.swift

@@ -26,6 +26,14 @@ func findJavaHome() -> String {
     return home
   }
 
+  // Detect we're on CI and try to guess the JAVA_HOME for the shared Swift Soundness scripts
+  if ProcessInfo.processInfo.environment["GITHUB_ACTIONS"] != nil {
+    let defaultCIJDKPath = "/usr/lib/jvm/default-jdk"
+    if FileManager.default.fileExists(atPath: defaultCIJDKPath) {
+      return defaultCIJDKPath
+    }
+  }
+
   fatalError("Please set the JAVA_HOME environment variable to point to where Java is installed.")
 }
 let javaHome = findJavaHome()
@@ -139,14 +147,6 @@ let package = Package(
         "JExtractSwiftCommandPlugin"
       ]
     ),
-
-    // ==== Examples
-
-    .library(
-      name: "ExampleSwiftLibrary",
-      type: .dynamic,
-      targets: ["ExampleSwiftLibrary"]
-    ),
 
   ],
   dependencies: [
@@ -155,6 +155,11 @@ let package = Package(
     .package(url: "https://github.com/ordo-one/package-benchmark", .upToNextMajor(from: "1.4.0")),
   ],
   targets: [
+    // Main target which serves as landing page for documentation
+    .target(
+      name: "SwiftJava"
+    ),
+
     .macro(
       name: "JavaKitMacros",
       dependencies: [
@@ -257,14 +262,6 @@ let package = Package(
       ]
     ),
 
-    .target(
-      name: "ExampleSwiftLibrary",
-      dependencies: [],
-      swiftSettings: [
-        .swiftLanguageMode(.v5),
-        .unsafeFlags(["-I\(javaIncludePath)", "-I\(javaPlatformIncludePath)"])
-      ]
-    ),
     .target(
       name: "SwiftKitSwift",
       dependencies: [],
@@ -413,3 +410,12 @@ let package = Package(
     )
   ]
 )
+
+switch ProcessInfo.processInfo.environment["SWIFT_DOCC"] {
+case "true", "TRUE", "yes", "YES", "1":
+  package.dependencies.append(
+    .package(url: "https://github.com/swiftlang/swift-docc-plugin", "1.0.0"..<"1.4.0")
+  )
+default:
+  ()
+}

Sources/JExtractSwift/JExtractSwift.docc/JExtractSwift.md

@@ -0,0 +1,62 @@
+# JExtractSwift
+
+The `jextract` approach to Java interoperability is primarily aimed at Java consumers of Swift libraries,
+and currently makes use of the [JDK-23 Foreign Function and Memory APIs](https://docs.oracle.com/en/java/javase/23/core/foreign-function-and-memory-api.html).
+
+- **No code changes** need to be made to Swift libraries that are to be exposed to Java using jextract-swift.
+- Swift sources are compiled to `.swiftinterface` files
+- These `.swiftinterface` files are imported by jextract-swift which generates `*.java` files
+- The generated Java files contain generated code for efficient native invocations.
+
+You can then use Swift libraries in Java just by calling the apropriate methods and initializers.
+
+## Getting Started
+
+This repository also includes the `jextract-swift` tool which is similar to the JDK's [`jextract`](https://github.com/openjdk/jextract/).
+
+This approach is using Java's most recent (stable in JDK22) Foreign function and Memory APIs, collectively known as "Project Panama". You can read more about it here: https://openjdk.org/projects/panama/ It promises much higher performance than traditional approaches using JNI, and is primarily aimed for calling native code from a Java application.
+
+:warning: This feature requires JDK 22. The recommended way to install/manage JDKs is using [sdkman](https://sdkman.io):
+
+```
+curl -s "https://get.sdkman.io" | bash
+sdk install java 22-open
+
+export JAVA_HOME=$(sdk home java 22-open)
+```
+
+`jextract-swift` can be pointed at `*.swiftinterface` files and will generate corresponding Java files that use the (new in Java 22) Foreign Function & Memory APIs to expose efficient ways to call "down" into Swift from Java.
+
+## JExtract: Swift <-> Java Type mapping
+
+### Closures and Callbacks
+
+A Swift function may accept a closure which is used as a callback:
+
+```swift
+func callMe(maybe: () -> ()) {}
+```
+
+
+## `jextract-swift` importer behavior
+
+Only `public` functions, properties and types are imported.
+
+Global Swift functions become static functions on on a class with the same name as the Swift module in Java,
+
+```swift
+// Swift (Sources/SomeModule/Example.swift)
+
+public func globalFunction()
+```
+
+becomes:
+
+```java
+// Java (SomeModule.java)
+
+public final class SomeModule ... {
+    public static void globalFunction() { ... }
+}
+```
+