wrap-java add basic docs with java signature to @JavaMethods (#523)

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!
         }