From eb85ff269b158d1ceddfa15df200df38c8e4cb41 Mon Sep 17 00:00:00 2001
From: Konrad Malawski <ktoso@apple.com>
Date: Fri, 16 Jan 2026 14:55:54 +0900
Subject: [PATCH] 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...
---
 .../JavaClassTranslator.swift                 | 17 ++++++++-
 .../WrapJavaTests/BasicWrapJavaTests.swift    | 36 +++++++++++++++++++
 .../WrapJavaTests/GenericsWrapJavaTests.swift |  6 ++--
 3 files changed, 54 insertions(+), 5 deletions(-)

diff --git a/Sources/SwiftJavaToolLib/JavaClassTranslator.swift b/Sources/SwiftJavaToolLib/JavaClassTranslator.swift
index ea0a793a..b355fc0c 100644
--- a/Sources/SwiftJavaToolLib/JavaClassTranslator.swift
+++ b/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)
         """
     }
diff --git a/Tests/SwiftJavaToolLibTests/WrapJavaTests/BasicWrapJavaTests.swift b/Tests/SwiftJavaToolLibTests/WrapJavaTests/BasicWrapJavaTests.swift
index e6f00ee8..9e167cf4 100644
--- a/Tests/SwiftJavaToolLibTests/WrapJavaTests/BasicWrapJavaTests.swift
+++ b/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(
       """
diff --git a/Tests/SwiftJavaToolLibTests/WrapJavaTests/GenericsWrapJavaTests.swift b/Tests/SwiftJavaToolLibTests/WrapJavaTests/GenericsWrapJavaTests.swift
index 60d5a331..b93d42e0 100644
--- a/Tests/SwiftJavaToolLibTests/WrapJavaTests/GenericsWrapJavaTests.swift
+++ b/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!
         }