Update structure of docs to use snippets

Author: ktoso

Samples/JavaDependencySampleApp/Sources/JavaDependencySample/main.swift

@@ -28,6 +28,7 @@ print("Start Sample app...")
 // TODO: locating the classpath is more complex, need to account for dependencies of our module
 let swiftJavaClasspath = findSwiftJavaClasspaths() // scans for .classpath files
 
+// snippet.dependencyUsage
 // 1) Start a JVM with appropriate classpath
 let jvm = try JavaVirtualMachine.shared(classpath: swiftJavaClasspath)
 
@@ -50,5 +51,6 @@ for record in try CSVFormatClass.RFC4180.parse(reader)!.getRecords()! {
     print("Field: \(field)")
   }
 }
+// snippet.end
 
 print("Done.")

Samples/JavaKitSampleApp/Sources/JavaKitExample/JavaKitExample.swift

@@ -19,6 +19,7 @@ enum SwiftWrappedError: Error {
   case message(String)
 }
 
+// snippet.implementation
 @JavaImplementation("com.example.swift.HelloSwift")
 extension HelloSwift: HelloSwiftNativeMethods {
   @JavaMethod
@@ -27,20 +28,24 @@ extension HelloSwift: HelloSwiftNativeMethods {
     let answer = self.sayHelloBack(i + j)
     print("Swift got back \(answer) from Java")
 
+    // snippet.staticFieldAccess
     print("We expect the above value to be the initial value, \(self.javaClass.initialValue)")
+    // snippet.end
 
     print("Updating Java field value to something different")
     self.value = 2.71828
 
     let newAnswer = self.sayHelloBack(17)
     print("Swift got back updated \(newAnswer) from Java")
 
+    // snippet.classDefinition
     let newHello = HelloSwift(environment: javaEnvironment)
     print("Swift created a new Java instance with the value \(newHello.value)")
 
     let name = newHello.name
     print("Hello to \(name)")
     newHello.greet("Swift 👋🏽 How's it going")
+    // snippet.end
 
     self.name = "a 🗑️-collected language"
     _ = self.sayHelloBack(42)
@@ -49,9 +54,12 @@ extension HelloSwift: HelloSwiftNativeMethods {
     let value = predicate.test(JavaInteger(3))
     print("Running a JavaPredicate from swift 3 < 10 = \(value)")
 
+    // snippet.arraysWrapper
     let strings = doublesToStrings([3.14159, 2.71828])
     print("Converting doubles to strings: \(strings)")
+    // snippet.end
 
+    // snippet.castPattern
     // Try downcasting
     if let helloSub = self.as(HelloSubclass.self) {
       print("Hello from the subclass!")
@@ -61,6 +69,7 @@ extension HelloSwift: HelloSwiftNativeMethods {
     } else {
       fatalError("Expected subclass here")
     }
+    // snippet.end
 
     // Check escaped name
     assert(self.`init`(42) == 42)
@@ -70,25 +79,34 @@ extension HelloSwift: HelloSwiftNativeMethods {
     assert(newHello.is(HelloSwift.self))
     assert(!newHello.is(HelloSubclass.self))
 
-    // Create a new instance.
+    // snippet.inheritance
+    // Create a new instance of the subclass; Swift mirrors the Java hierarchy.
     let helloSubFromSwift = HelloSubclass("Hello from Swift", environment: javaEnvironment)
     helloSubFromSwift.greetMe()
+    // snippet.end
 
+    // snippet.throwingMethods
     do {
       try throwMessage("I am an error")
     } catch {
       print("Caught Java error: \(error)")
     }
+    // snippet.end
 
-    // Make sure that the thread safe class is sendable
+    // snippet.sendableConformance
+    // Java classes annotated with @ThreadSafe surface as Sendable on the Swift side.
     let helper = ThreadSafeHelperClass(environment: javaEnvironment)
     let threadSafe: Sendable = helper
+    _ = threadSafe
+    // snippet.end
 
     checkOptionals(helper: helper)
 
     return i * j
   }
+  // snippet.end
 
+  // snippet.optionalsWrapper
   func checkOptionals(helper: ThreadSafeHelperClass) {
     let text: JavaString? = helper.textOptional
     let value: String? = helper.getValueOptional(Optional<JavaString>.none)
@@ -101,6 +119,7 @@ extension HelloSwift: HelloSwiftNativeMethods {
     print("Optional double function returned \(doubleOpt)")
     print("Optional long function returned \(longOpt)")
   }
+  // snippet.end
 
   @JavaMethod
   func throwMessageFromSwift(_ message: String) throws -> String {

Samples/JavaKitSampleApp/Sources/JavaKitExample/com/example/swift/HelloJavaKitArrays.java

@@ -14,6 +14,7 @@
 
 package com.example.swift;
 
+// snippet.arrays
 public class HelloJavaKitArrays {
 
     public byte[] getFixedBytes() {
@@ -57,3 +58,4 @@ public String[] getGreetings() {
         return new String[] { "hello", "world", "from", "java" };
     }
 }
+// snippet.end

Samples/JavaKitSampleApp/Sources/JavaKitExample/com/example/swift/HelloSubclass.java

@@ -14,6 +14,7 @@
 
 package com.example.swift;
 
+// snippet.helloSubclass
 public class HelloSubclass extends HelloSwift {
     private String greeting;
 
@@ -25,3 +26,4 @@ public void greetMe() {
         super.greet(greeting);
     }
 }
+// snippet.end

Samples/JavaKitSampleApp/Sources/JavaKitExample/com/example/swift/HelloSwift.java

@@ -16,6 +16,7 @@
 
 import java.util.function.Predicate;
 
+// snippet.helloClass
 public class HelloSwift {
     public double value;
     public static double initialValue = 3.14159;
@@ -71,3 +72,4 @@ public void throwMessage(String message) throws Exception {
         throw new Exception(message);
     }
 }
+// snippet.end

Samples/JavaKitSampleApp/Sources/JavaKitExample/com/example/swift/ThreadSafe.java

@@ -17,6 +17,8 @@
 import java.lang.annotation.Retention;
 import java.lang.annotation.RetentionPolicy;
 
+// snippet.threadSafe
 @Retention(RetentionPolicy.RUNTIME)
 public @interface ThreadSafe {
 }
+// snippet.end

Samples/JavaKitSampleApp/Sources/JavaKitExample/com/example/swift/ThreadSafeHelperClass.java

@@ -19,6 +19,7 @@
 import java.util.OptionalInt;
 import java.util.OptionalDouble;
 
+// snippet.threadSafeHelper
 @ThreadSafe
 public class ThreadSafeHelperClass {
     public ThreadSafeHelperClass() { }
@@ -53,3 +54,4 @@ public OptionalLong from(OptionalInt value) {
         return OptionalLong.of(value.getAsInt());
     }
 }
+// snippet.end

Samples/JavaKitSampleApp/Tests/JavaKitExampleTests/JavaKitArrayRuntimeTests.swift

@@ -21,6 +21,7 @@ struct JavaKitArrayRuntimeTests {
 
   let jvm = try JavaKitSampleJVM.shared
 
+  // snippet.arraysUsage
   @Test
   func getFixedBytes() throws {
     let env = try jvm.environment()
@@ -31,30 +32,40 @@ struct JavaKitArrayRuntimeTests {
   }
 
   @Test
-  func getEmptyBytes() throws {
+  func reverseBytes() throws {
     let env = try jvm.environment()
     let arrays = HelloJavaKitArrays(environment: env)
 
-    let bytes: [Int8] = arrays.getEmptyBytes()
-    #expect(bytes.isEmpty)
+    let reversed: [Int8] = arrays.reverseBytes([10, 20, 30])
+    #expect(reversed == [30, 20, 10])
   }
 
   @Test
-  func filledBytes() throws {
+  func getGreetings() throws {
     let env = try jvm.environment()
     let arrays = HelloJavaKitArrays(environment: env)
 
-    let bytes: [Int8] = arrays.filledBytes(4, 42)
-    #expect(bytes == [42, 42, 42, 42])
+    let greetings: [String] = arrays.getGreetings()
+    #expect(greetings == ["hello", "world", "from", "java"])
   }
+  // snippet.end
 
   @Test
-  func reverseBytes() throws {
+  func getEmptyBytes() throws {
     let env = try jvm.environment()
     let arrays = HelloJavaKitArrays(environment: env)
 
-    let reversed: [Int8] = arrays.reverseBytes([10, 20, 30])
-    #expect(reversed == [30, 20, 10])
+    let bytes: [Int8] = arrays.getEmptyBytes()
+    #expect(bytes.isEmpty)
+  }
+
+  @Test
+  func filledBytes() throws {
+    let env = try jvm.environment()
+    let arrays = HelloJavaKitArrays(environment: env)
+
+    let bytes: [Int8] = arrays.filledBytes(4, 42)
+    #expect(bytes == [42, 42, 42, 42])
   }
 
   @Test
@@ -84,13 +95,4 @@ struct JavaKitArrayRuntimeTests {
     // "Hi" in UTF-8 is [0x48, 0x69]
     #expect(bytes == [0x48, 0x69])
   }
-
-  @Test
-  func getGreetings() throws {
-    let env = try jvm.environment()
-    let arrays = HelloJavaKitArrays(environment: env)
-
-    let greetings: [String] = arrays.getGreetings()
-    #expect(greetings == ["hello", "world", "from", "java"])
-  }
 }

Samples/JavaProbablyPrime/Sources/JavaProbablyPrime/prime.swift

@@ -24,11 +24,13 @@ struct ProbablyPrime: ParsableCommand {
   var certainty: Int32 = 10
 
   func run() throws {
+    // snippet.probablyPrime
     let bigInt = BigInteger(number)
     if bigInt.isProbablePrime(certainty) {
       print("\(number) is probably prime")
     } else {
       print("\(number) is definitely not prime")
     }
+    // snippet.end
   }
 }

Samples/JavaSieve/Sources/JavaSieve/main.swift

@@ -17,6 +17,7 @@ import SwiftJava
 
 let jvm = try JavaVirtualMachine.shared()
 
+// snippet.sieveUsage
 do {
   let sieveClass = try JavaClass<SieveOfEratosthenes>(environment: jvm.environment())
   for prime in sieveClass.findPrimes(100)! {
@@ -27,3 +28,4 @@ do {
 } catch {
   print("Failure: \(error)")
 }
+// snippet.end