Merge remote-tracking branch 'origin' into swift-java-documentation

Author: koloyyee

Sources/SwiftJavaDocumentation/Documentation.docc/SupportedFeatures.md

@@ -33,10 +33,10 @@ Java `native` functions. JavaKit simplifies the type conversions
 | Java `abstract class`                  | TODO          |
 | Java `enum`                            | ❌             |
 | Java methods: `static`, member           | ✅ `@JavaMethod` |
-| **This list is very work in progress** |               |
+| **This list is very work in progress** |               |    
 
 
-### JExtract: Java -> Swift
+### JExtract – calling Swift from Java
 
 SwiftJava's `swift-java jextract` tool automates generating Java bindings to Swift sources.
 

Sources/SwiftJavaDocumentation/Documentation.docc/index.md

@@ -11,24 +11,19 @@ Please refer to articles about the specific direction of interoperability you ar
 
 ### Getting started
 
-**SwiftJava** provides Java and Swift interoperability with minimal overhead. It eliminates the complex, error-prone process such as manually compiling Java classes to C headers for native access. With SwiftJava, developers can achieve a flexible, safe, and high-performance connection between the two languages.
+**SwiftJava** provides a set of tools and libraries to enable Java and Swift interoperability. It allows developers to generate bindings to either language from the other, by using either source generation (for Java consuming Swift code) or a combination of Swift macros and source generation (for Swift consuming Java libraries).
 
-**Interoperability promotes**
-- Incremental adoption of Swift
-- Reuse of libraries across languages
-    - Access libraries with or without native APIs
-    - Implement performance-sensitive code in Swift
-- Support for ecosystem-specific build tools
+The generated code is highly efficient and less error-prone than manually mapping, and also guarantees memory safety across the boundaries between the languages.
 
-**Tools**
-- Swift Package: 
-    - JavaKit (Java -> Swift)
-- Java Library: 
-    - SwiftKit (Swift -> Java)
-- Tooling: 
-    - swift-java: command line tool 
-    - Build tool integration: SwiftPM Plugin or Gradle 
+Reasons why you might want to reach for Swift and Java interoperability include, but are not limited to, the following scenarios:
+- Incremental adoption of Swift in an existing Java codebase
+- Reuse existing libraries which exist in one ecosystem, but don't have a direct equivalent in the other
 
+SwiftJava is offering several core libraries which support language interoperability:
+- `JavaKit` (Swift -> Java) - JNI-based support library and Swift macros
+- `SwiftKit` (Java -> Swift) - Support library for Java calling Swift code (either using JNI or FFM)
+- `swift-java` - command line tool; Supports source generation and also dependency management operations
+- Build tool integration - SwiftPM Plugin
 
 If you prefer a video introduction, you may want to watch this 
 [Explore Swift and Java interoperability](https://www.youtube.com/watch?v=QSHO-GUGidA) 
@@ -42,7 +37,7 @@ which is a quick overview of all the features and approaches offered by SwiftJav
 - <doc:SupportedFeatures>
 
 
-### Source generation
+### Source Generation
 
 - <doc:SwiftJavaCommandLineTool>
 - <doc:SwiftPMPlugin>