wrap-java add basic docs with java signature to @JavaMethods

Right now these are not super exciting but having the java signature
next to the wrapped Swift signature is helpful in detecting subtle
issues or understanding hwo types were mapped over

Further down the line I'd like to figure out including the original
javadoc, by fetching and resolving the javadoc jars etc...

Author: ktoso

Sources/SwiftJavaToolLib/JavaClassTranslator.swift

@@ -695,6 +695,20 @@ extension JavaClassTranslator {
     let swiftMethodName = javaMethod.getName().escapedSwiftName
     let swiftOptionalMethodName = "\(javaMethod.getName())Optional".escapedSwiftName
 
+    // --- Handle docs for the generated method.
+    // Include the original Java signature
+    let docsString = 
+      """
+        /**
+         * Java method `\(javaMethod.getName())`.
+         * 
+         * ### Java method signature
+         * ```java
+         * \(javaMethod.toGenericString())
+         * ```
+         */
+      """
+
     // Compute the parameters for '@...JavaMethod(...)'
     let methodAttribute: AttributeSyntax
       if implementedInSwift {
@@ -755,9 +769,9 @@ extension JavaClassTranslator {
           baseBody
         }
 
-
       return 
         """
+        \(raw: docsString)
         \(methodAttribute)\(raw: accessModifier)\(raw: overrideOpt)func \(raw: swiftMethodName)\(raw: genericParameterClauseStr)(\(raw: parametersStr))\(raw: throwsStr)\(raw: resultTypeStr)\(raw: whereClause)
         
         \(raw: accessModifier)\(raw: overrideOpt)func \(raw: swiftOptionalMethodName)\(raw: genericParameterClauseStr)(\(raw: parameters.map(\.clause.description).joined(separator: ", ")))\(raw: throwsStr) -> \(raw: resultOptional)\(raw: whereClause) {
@@ -767,6 +781,7 @@ extension JavaClassTranslator {
     } else {
       return 
         """
+        \(raw: docsString)
         \(methodAttribute)\(raw: accessModifier)\(raw: overrideOpt)func \(raw: swiftMethodName)\(raw: genericParameterClauseStr)(\(raw: parametersStr))\(raw: throwsStr)\(raw: resultTypeStr)\(raw: whereClause)
         """
     }

Tests/SwiftJavaToolLibTests/WrapJavaTests/BasicWrapJavaTests.swift

@@ -49,6 +49,42 @@ final class BasicWrapJavaTests: XCTestCase {
     )
   }
 
+  func testWrapJava_docs_signature() async throws {
+    let classpathURL = try await compileJava(
+      """
+      package com.example;
+
+      class ExampleSimpleClass {
+        public void example(String name, int age) { }
+      }
+      """)
+
+    try assertWrapJavaOutput(
+      javaClassNames: [
+        "com.example.ExampleSimpleClass"
+      ],
+      classpath: [classpathURL],
+      expectedChunks: [
+        """
+        import CSwiftJavaJNI
+        import SwiftJava
+        """,
+        """
+          /**
+           * Java method `example`.
+           *
+           * ### Java method signature
+           * ```java
+           * public void com.example.ExampleSimpleClass.example(java.lang.String,int)
+           * ```
+           */
+           @JavaMethod
+           open func example(_ arg0: String, _ arg1: Int32)
+        """
+      ]
+    )
+  }
+
   func test_wrapJava_doNotDupeImportNestedClassesFromSuperclassAutomatically() async throws {
     let classpathURL = try await compileJava(
       """

Tests/SwiftJavaToolLibTests/WrapJavaTests/GenericsWrapJavaTests.swift

@@ -257,10 +257,6 @@ final class GenericsWrapJavaTests: XCTestCase {
         @JavaClass("com.example.ByteArray")
         open class ByteArray: JavaObject {
         """,
-        // """
-        // @JavaInterface("com.example.Store")
-        // public struct Store<K: AnyJavaObject, V: AnyJavaObject, T: AnyJavaObject> {
-        // """,
         """
         @JavaClass("com.example.CompressingStore")
         open class CompressingStore: AbstractStore<ByteArray, [UInt8], [UInt8]> {
@@ -292,6 +288,8 @@ final class GenericsWrapJavaTests: XCTestCase {
         """
         @JavaClass("com.example.Kappa")
         open class Kappa<T: AnyJavaObject>: JavaObject {
+        """,
+        """
           @JavaMethod(typeErasedResult: "T!")
           open func get() -> T!
         }