[jnigen] Use Kotlin signature in the docs of Kotlin methods (#2418)

Fixes #1236.

Author: goderbauer

pkgs/jnigen/example/kotlin_plugin/lib/kotlin_bindings.dart

@@ -93,7 +93,7 @@ class Example extends jni$_.JObject {
           jni$_.JniResult Function(jni$_.Pointer<jni$_.Void>,
               jni$_.JMethodIDPtr, jni$_.Pointer<jni$_.Void>)>();
 
-  /// from: `public final java.lang.Object thinkBeforeAnswering(kotlin.coroutines.Continuation<? super java.lang.String> continuation)`
+  /// from: `public suspend fun thinkBeforeAnswering(): kotlin.String`
   /// The returned object must be released after use, by calling the [release] method.
   core$_.Future<jni$_.JString> thinkBeforeAnswering() async {
     final $p = jni$_.ReceivePort();

pkgs/jnigen/java/src/main/java/com/github/dart_lang/jnigen/apisummarizer/elements/KotlinFunction.java

@@ -27,6 +27,10 @@ public class KotlinFunction {
   public int flags;
   public boolean isSuspend;
   public boolean isOperator;
+  public boolean isPublic;
+  public boolean isPrivate;
+  public boolean isProtected;
+  public boolean isInternal;
 
   public static KotlinFunction fromKmFunction(KmFunction f) {
     var fun = new KotlinFunction();
@@ -52,6 +56,10 @@ public static KotlinFunction fromKmFunction(KmFunction f) {
         f.getTypeParameters().stream()
             .map(KotlinTypeParameter::fromKmTypeParameter)
             .collect(Collectors.toList());
+    fun.isPublic = Flag.IS_PUBLIC.invoke(fun.flags);
+    fun.isPrivate = Flag.IS_PRIVATE.invoke(fun.flags);
+    fun.isProtected = Flag.IS_PROTECTED.invoke(fun.flags);
+    fun.isInternal = Flag.IS_INTERNAL.invoke(fun.flags);
     return fun;
   }
 }

pkgs/jnigen/lib/src/bindings/dart_generator.dart

@@ -1365,10 +1365,15 @@ ${modifier}final _$name = $_protectedExtension
 
     // Docs
     s.write('  /// from: `');
-    s.writeAll(node.modifiers.map((m) => '$m '));
-    s.write('${node.returnType} ${node.name}(');
-    s.writeAll(node.params.map((p) => '${p.type} ${p.name}'), ', ');
-    s.writeln(')`');
+    if (node.kotlinFunction != null) {
+      _writeKotlinSignature(node);
+      s.writeln('`');
+    } else {
+      s.writeAll(node.modifiers.map((m) => '$m '));
+      s.write('${node.returnType} ${node.name}(');
+      s.writeAll(node.params.map((p) => '${p.type} ${p.name}'), ', ');
+      s.writeln(')`');
+    }
     if (node.returnType is! PrimitiveType || node.isConstructor) {
       s.writeln(_releaseInstruction);
     }
@@ -1509,6 +1514,67 @@ ${modifier}final _$name = $_protectedExtension
 ''');
     }
   }
+
+  void _writeKotlinSignature(Method node) {
+    final kotlinFunction = node.kotlinFunction!;
+    final typeParams = [
+      ...node.classDecl.allTypeParams,
+      ...node.typeParams,
+    ];
+
+    if (kotlinFunction.isPublic) {
+      s.write('public ');
+    }
+    if (kotlinFunction.isPrivate) {
+      s.write('private ');
+    }
+    if (kotlinFunction.isProtected) {
+      s.write('protected ');
+    }
+    if (kotlinFunction.isInternal) {
+      s.write('internal ');
+    }
+    if (kotlinFunction.isSuspend) {
+      s.write('suspend ');
+    }
+    if (kotlinFunction.isOperator) {
+      s.write('operator ');
+    }
+    s.write('fun ');
+    final whereClauses = <String>[];
+    if (kotlinFunction.typeParameters.isNotEmpty) {
+      s.write('<');
+      for (final t in kotlinFunction.typeParameters) {
+        final typeParameters = t.upperBounds
+            .map((bound) => '${t.name} : ${bound.toDocComment(typeParams)}');
+        if (typeParameters.length == 1) {
+          s.write(typeParameters.single);
+        } else {
+          s.write(t.name);
+          whereClauses.addAll(typeParameters);
+        }
+      }
+      s.write('> ');
+    }
+    s.write('${kotlinFunction.kotlinName}(');
+    s.writeAll(kotlinFunction.valueParameters.map((p) {
+      final KotlinType type;
+      final String prefix;
+      if (p.varargElementType != null) {
+        prefix = 'vararg ';
+        type = p.varargElementType!;
+      } else {
+        prefix = '';
+        type = p.type;
+      }
+      return '$prefix${p.name}: ${type.toDocComment(typeParams)}';
+    }), ', ');
+    s.write('): ${kotlinFunction.returnType.toDocComment(typeParams)}');
+    if (whereClauses.isNotEmpty) {
+      s.write(' where ');
+      s.writeAll(whereClauses, ', ');
+    }
+  }
 }
 
 /// Generates the method type param definition.

pkgs/jnigen/lib/src/elements/elements.dart

@@ -1158,6 +1158,10 @@ class KotlinFunction {
     required this.flags,
     required this.isSuspend,
     required this.isOperator,
+    required this.isPublic,
+    required this.isPrivate,
+    required this.isProtected,
+    required this.isInternal,
   });
 
   /// Name in the byte code.
@@ -1175,6 +1179,10 @@ class KotlinFunction {
   final int flags;
   final bool isSuspend;
   final bool isOperator;
+  final bool isPublic;
+  final bool isPrivate;
+  final bool isProtected;
+  final bool isInternal;
 
   factory KotlinFunction.fromJson(Map<String, dynamic> json) =>
       _$KotlinFunctionFromJson(json);
@@ -1282,6 +1290,19 @@ class KotlinType implements Element<KotlinType> {
   R accept<R>(Visitor<KotlinType, R> v) {
     return v.visit(this);
   }
+
+  String? toDocComment(List<TypeParam> typeParametersByIndex) {
+    final typeList = arguments.map((a) => switch (a) {
+          KotlinWildcard() => '*',
+          KotlinTypeProjection() => a.type.toDocComment(typeParametersByIndex),
+        });
+    final typeArgs = typeList.isNotEmpty ? '<${typeList.join(', ')}>' : '';
+    final typeName = name == null
+        ? typeParametersByIndex[id].name
+        // Translate JVM internal form (aka binary name form) to Kotlin form.
+        : name!.replaceAll('/', '.').replaceAll('\$', '.');
+    return '$typeName$typeArgs${isNullable ? '?' : ''}';
+  }
 }
 
 @JsonEnum()