Add struct and enum doc comments in Java

diff --git a/bindingstypes.py b/bindingstypes.py
index 66f34a58340158c566284475c7addd65de453038..aab05250a9d9f9a9afa246abb4b726af24503e04 100644 (file)
--- a/bindingstypes.py
+++ b/bindingstypes.py
@@ -66,11 +66,12 @@ class ConvInfo:
         self.from_hu_conv = from_hu_conv
 
 class TraitMethInfo:
-    def __init__(self, fn_name, self_is_const, ret_ty_info, args_ty):
+    def __init__(self, fn_name, self_is_const, ret_ty_info, args_ty, docs):
         self.fn_name = fn_name
         self.self_is_const = self_is_const
         self.ret_ty_info = ret_ty_info
         self.args_ty = args_ty
+        self.docs = docs
 
 class ComplexEnumVariantInfo:
     def __init__(self, var_name, fields):

diff --git a/genbindings.py b/genbindings.py
index ca88a3aa989fe43792e5521cf7e6d2d264902cd6..124a76bac1e2688b9fbdc3ea1d29a7db645986f8 100755 (executable)
--- a/genbindings.py
+++ b/genbindings.py
@@ -369,7 +369,7 @@ with open(f"{sys.argv[3]}/structs/UtilMethods{consts.file_ext}", "a") as util:
 
 with open(sys.argv[1]) as in_h, open(sys.argv[2], "w") as out_java:
     # Map a top-level function
-    def map_fn(line, re_match, ret_arr_len, c_call_string):
+    def map_fn(line, re_match, ret_arr_len, c_call_string, doc_comment):
         method_return_type = re_match.group(1)
         method_name = re_match.group(2)
         method_comma_separated_arguments = re_match.group(3)
@@ -405,7 +405,8 @@ with open(sys.argv[1]) as in_h, open(sys.argv[2], "w") as out_java:
             argument_types.append(argument_conversion_info)
 
         out_java.write("\t// " + line)
-        (out_java_delta, out_c_delta, out_java_struct_delta) = consts.map_function(argument_types, c_call_string, method_name, return_type_info, struct_meth, default_constructor_args, takes_self, args_known, type_mapping_generator)
+        (out_java_delta, out_c_delta, out_java_struct_delta) = \
+            consts.map_function(argument_types, c_call_string, method_name, return_type_info, struct_meth, default_constructor_args, takes_self, args_known, type_mapping_generator, doc_comment)
         out_java.write(out_java_delta)
 
         if is_free:
@@ -439,7 +440,7 @@ with open(sys.argv[1]) as in_h, open(sys.argv[2], "w") as out_java:
         if out_java_struct is not None:
             out_java_struct.write(out_java_struct_delta)
 
-    def map_unitary_enum(struct_name, field_lines):
+    def map_unitary_enum(struct_name, field_lines, enum_doc_comment):
         with open(f"{sys.argv[3]}/enums/{struct_name}{consts.file_ext}", "w") as out_java_enum:
             unitary_enums.add(struct_name)
             for idx, struct_line in enumerate(field_lines):
@@ -451,12 +452,12 @@ with open(sys.argv[1]) as in_h, open(sys.argv[2], "w") as out_java:
                     assert(struct_line == "} %s;" % struct_name)
                 elif idx == len(field_lines) - 1:
                     assert(struct_line == "")
-            (c_out, native_file_out, native_out) = consts.native_c_unitary_enum_map(struct_name, [x.strip().strip(",") for x in field_lines[1:-3]])
+            (c_out, native_file_out, native_out) = consts.native_c_unitary_enum_map(struct_name, [x.strip().strip(",") for x in field_lines[1:-3]], enum_doc_comment)
             write_c(c_out)
             out_java_enum.write(native_file_out)
             out_java.write(native_out)
 
-    def map_complex_enum(struct_name, union_enum_items):
+    def map_complex_enum(struct_name, union_enum_items, enum_doc_comment):
         java_hu_type = struct_name.replace("LDK", "")
         complex_enums.add(struct_name)
 
@@ -488,13 +489,13 @@ with open(sys.argv[1]) as in_h, open(sys.argv[2], "w") as out_java:
                 enum_variants.append(ComplexEnumVariantInfo(variant_name, fields))
 
         with open(f"{sys.argv[3]}/structs/{java_hu_type}{consts.file_ext}", "w") as out_java_enum:
-            (out_java_addendum, out_java_enum_addendum, out_c_addendum) = consts.map_complex_enum(struct_name, enum_variants, camel_to_snake)
+            (out_java_addendum, out_java_enum_addendum, out_c_addendum) = consts.map_complex_enum(struct_name, enum_variants, camel_to_snake, enum_doc_comment)
 
             out_java_enum.write(out_java_enum_addendum)
             out_java.write(out_java_addendum)
             write_c(out_c_addendum)
 
-    def map_trait(struct_name, field_var_lines, trait_fn_lines):
+    def map_trait(struct_name, field_var_lines, trait_fn_lines, trait_doc_comment):
         with open(f"{sys.argv[3]}/structs/{struct_name.replace('LDK', '')}{consts.file_ext}", "w") as out_java_trait:
             field_var_convs = []
             for var_line in field_var_lines:
@@ -505,7 +506,7 @@ with open(sys.argv[1]) as in_h, open(sys.argv[2], "w") as out_java:
                         type_mapping_generator.map_type(var_line.group(1) + " " + var_line.group(2), False, None, False, False))
 
             field_fns = []
-            for fn_line in trait_fn_lines:
+            for fn_docs, fn_line in trait_fn_lines:
                 ret_ty_info = type_mapping_generator.map_type(fn_line.group(2), True, None, False, False)
                 is_const = fn_line.group(4) is not None
 
@@ -515,19 +516,19 @@ with open(sys.argv[1]) as in_h, open(sys.argv[2], "w") as out_java:
                         continue
                     arg_conv_info = type_mapping_generator.map_type(arg, True, None, False, False)
                     arg_tys.append(arg_conv_info)
-                field_fns.append(TraitMethInfo(fn_line.group(3), is_const, ret_ty_info, arg_tys))
+                field_fns.append(TraitMethInfo(fn_line.group(3), is_const, ret_ty_info, arg_tys, fn_docs))
 
-            (out_java_addendum, out_java_trait_addendum, out_c_addendum) = consts.native_c_map_trait(struct_name, field_var_convs, field_fns)
+            (out_java_addendum, out_java_trait_addendum, out_c_addendum) = consts.native_c_map_trait(struct_name, field_var_convs, field_fns, trait_doc_comment)
             write_c(out_c_addendum)
             out_java_trait.write(out_java_trait_addendum)
             out_java.write(out_java_addendum)
 
-        for fn_line in trait_fn_lines:
+        for fn_docs, fn_line in trait_fn_lines:
             # For now, just disable enabling the _call_log - we don't know how to inverse-map String
             is_log = fn_line.group(3) == "log" and struct_name == "LDKLogger"
             if fn_line.group(3) != "free" and fn_line.group(3) != "clone" and fn_line.group(3) != "eq" and not is_log:
                 dummy_line = fn_line.group(2) + struct_name.replace("LDK", "") + "_" + fn_line.group(3) + " " + struct_name + "* this_arg" + fn_line.group(5) + "\n"
-                map_fn(dummy_line, re.compile("([A-Za-z_0-9]*) *([A-Za-z_0-9]*) *(.*)").match(dummy_line), None, "(this_arg_conv->" + fn_line.group(3) + ")(this_arg_conv->this_arg")
+                map_fn(dummy_line, re.compile("([A-Za-z_0-9]*) *([A-Za-z_0-9]*) *(.*)").match(dummy_line), None, "(this_arg_conv->" + fn_line.group(3) + ")(this_arg_conv->this_arg", fn_docs)
         for idx, var_line in enumerate(field_var_lines):
             if var_line.group(1) not in trait_structs:
                 write_c(var_line.group(1) + " " + struct_name + "_set_get_" + var_line.group(2) + "(" + struct_name + "* this_arg) {\n")
@@ -536,7 +537,7 @@ with open(sys.argv[1]) as in_h, open(sys.argv[2], "w") as out_java:
                 write_c("\treturn this_arg->" + var_line.group(2) + ";\n")
                 write_c("}\n")
                 dummy_line = var_line.group(1) + " " + struct_name.replace("LDK", "") + "_get_" + var_line.group(2) + " " + struct_name + "* this_arg" + fn_line.group(5) + "\n"
-                map_fn(dummy_line, re.compile("([A-Za-z_0-9]*) *([A-Za-z_0-9]*) *(.*)").match(dummy_line), None, struct_name + "_set_get_" + var_line.group(2) + "(this_arg_conv")
+                map_fn(dummy_line, re.compile("([A-Za-z_0-9]*) *([A-Za-z_0-9]*) *(.*)").match(dummy_line), None, struct_name + "_set_get_" + var_line.group(2) + "(this_arg_conv", fn_docs)
 
     def map_result(struct_name, res_ty, err_ty):
         result_types.add(struct_name)
@@ -694,7 +695,8 @@ with open(sys.argv[1]) as in_h, open(sys.argv[2], "w") as out_java:
     with open(f"{sys.argv[3]}/structs/CommonBase{consts.file_ext}", "w") as out_java_struct:
         out_java_struct.write(consts.common_base)
 
-    in_block_comment = False
+    block_comment = None
+    last_block_comment = None
     cur_block_obj = None
 
     const_val_regex = re.compile("^extern const ([A-Za-z_0-9]*) ([A-Za-z_0-9]*);$")
@@ -717,9 +719,12 @@ with open(sys.argv[1]) as in_h, open(sys.argv[2], "w") as out_java:
     union_enum_items = {}
     result_ptr_struct_items = {}
     for line in in_h:
-        if in_block_comment:
+        if block_comment is not None:
             if line.endswith("*/\n"):
-                in_block_comment = False
+                last_block_comment = block_comment.strip("\n")
+                block_comment = None
+            else:
+                block_comment = block_comment + line.strip(" /*")
         elif cur_block_obj is not None:
             cur_block_obj  = cur_block_obj + line
             if line.startswith("} "):
@@ -738,10 +743,13 @@ with open(sys.argv[1]) as in_h, open(sys.argv[2], "w") as out_java:
 
                 for idx, struct_line in enumerate(obj_lines):
                     if struct_line.strip().startswith("/*"):
-                        in_block_comment = True
-                    if in_block_comment:
+                        block_comment = struct_line.strip(" /*")
+                    if block_comment is not None:
                         if struct_line.endswith("*/"):
-                            in_block_comment = False
+                            last_struct_block_comment = block_comment.strip("\n")
+                            block_comment = None
+                        else:
+                            block_comment = block_comment + "\n" + struct_line.strip(" /*")
                     else:
                         struct_name_match = struct_name_regex.match(struct_line)
                         if struct_name_match is not None:
@@ -765,7 +773,7 @@ with open(sys.argv[1]) as in_h, open(sys.argv[2], "w") as out_java:
                             is_tuple = True
                         trait_fn_match = line_indicates_trait_regex.match(struct_line)
                         if trait_fn_match is not None:
-                            trait_fn_lines.append(trait_fn_match)
+                            trait_fn_lines.append((last_struct_block_comment, trait_fn_match))
                         field_var_match = line_field_var_regex.match(struct_line)
                         if field_var_match is not None:
                             field_var_lines.append(field_var_match)
@@ -783,7 +791,8 @@ with open(sys.argv[1]) as in_h, open(sys.argv[2], "w") as out_java:
                 if is_opaque:
                     opaque_structs.add(struct_name)
                     with open(f"{sys.argv[3]}/structs/{struct_name.replace('LDK', '')}{consts.file_ext}", "w") as out_java_struct:
-                        out_opaque_struct_human = consts.map_opaque_struct(struct_name)
+                        out_opaque_struct_human = consts.map_opaque_struct(struct_name, last_block_comment)
+                        last_block_comment = None
                         out_java_struct.write(out_opaque_struct_human)
                 elif result_contents is not None:
                     assert result_contents in result_ptr_struct_items
@@ -850,12 +859,14 @@ with open(sys.argv[1]) as in_h, open(sys.argv[2], "w") as out_java:
                     enum_var_name = struct_name.split("_")
                     union_enum_items[enum_var_name[0]][enum_var_name[1]] = field_lines
                 elif struct_name in union_enum_items:
-                    map_complex_enum(struct_name, union_enum_items[struct_name])
+                    map_complex_enum(struct_name, union_enum_items[struct_name], last_block_comment)
+                    last_block_comment = None
                 elif is_unitary_enum:
-                    map_unitary_enum(struct_name, field_lines)
+                    map_unitary_enum(struct_name, field_lines, last_block_comment)
+                    last_block_comment = None
                 elif len(trait_fn_lines) > 0:
                     trait_structs.add(struct_name)
-                    map_trait(struct_name, field_var_lines, trait_fn_lines)
+                    map_trait(struct_name, field_var_lines, trait_fn_lines, last_block_comment)
                 elif struct_name == "LDKTxOut":
                     with open(f"{sys.argv[3]}/structs/TxOut{consts.file_ext}", "w") as out_java_struct:
                         out_java_struct.write(consts.hu_struct_file_prefix)
@@ -881,9 +892,8 @@ with open(sys.argv[1]) as in_h, open(sys.argv[2], "w") as out_java:
             if line.startswith("#include <"):
                 pass
             elif line.startswith("/*"):
-                #out_java.write("\t" + line)
                 if not line.endswith("*/\n"):
-                    in_block_comment = True
+                    block_comment = line.strip(" /*")
             elif line.startswith("typedef enum "):
                 cur_block_obj = line
             elif line.startswith("typedef struct "):
@@ -891,11 +901,14 @@ with open(sys.argv[1]) as in_h, open(sys.argv[2], "w") as out_java:
             elif line.startswith("typedef union "):
                 cur_block_obj = line
             elif fn_ptr is not None:
-                map_fn(line, fn_ptr, None, None)
+                map_fn(line, fn_ptr, None, None, last_block_comment)
+                last_block_comment = None
             elif fn_ret_arr is not None:
-                map_fn(line, fn_ret_arr, fn_ret_arr.group(4), None)
+                map_fn(line, fn_ret_arr, fn_ret_arr.group(4), None, last_block_comment)
+                last_block_comment = None
             elif reg_fn is not None:
-                map_fn(line, reg_fn, None, None)
+                map_fn(line, reg_fn, None, None, last_block_comment)
+                last_block_comment = None
             elif const_val_regex is not None:
                 # TODO Map const variables
                 pass

diff --git a/java_strings.py b/java_strings.py
index 4b2ae77fe7f308cfddf7d278071c7bf6ad06a14a..d827da9e05f62d586e0605568cdb8c579b2ab64f 100644 (file)
--- a/java_strings.py
+++ b/java_strings.py
@@ -320,7 +320,6 @@ import org.ldk.enums.*;
 import org.ldk.util.*;
 import java.util.Arrays;
 
-@SuppressWarnings("unchecked") // We correctly assign various generic arrays
 """
         self.c_fn_ty_pfx = "JNIEXPORT "
         self.c_fn_args_pfx = "JNIEnv *env, jclass clz"
@@ -398,14 +397,16 @@ import java.util.Arrays;
         res = res + "}\n"
         return res
 
-    def native_c_unitary_enum_map(self, struct_name, variants):
+    def native_c_unitary_enum_map(self, struct_name, variants, enum_doc_comment):
         out_java_enum = "package org.ldk.enums;\n\n"
         out_java = ""
         out_c = ""
         out_c = out_c + "static inline " + struct_name + " " + struct_name + "_from_java(" + self.c_fn_args_pfx + ") {\n"
         out_c = out_c + "\tswitch ((*env)->CallIntMethod(env, clz, ordinal_meth)) {\n"
 
-        out_java_enum = out_java_enum + "public enum " + struct_name + " {\n"
+        if enum_doc_comment is not None:
+            out_java_enum += "/**\n * " + enum_doc_comment.replace("\n", "\n * ") + "\n */\n"
+        out_java_enum += "public enum " + struct_name + " {\n"
         ord_v = 0
         for var in variants:
             out_java_enum = out_java_enum + "\t" + var + ",\n"
@@ -474,12 +475,15 @@ import java.util.Arrays;
             ret = ret + ", " + param
         return ret + ")"
 
-    def native_c_map_trait(self, struct_name, field_vars, field_fns):
+    def native_c_map_trait(self, struct_name, field_vars, field_fns, trait_doc_comment):
         out_java_trait = ""
         out_java = ""
 
         # First generate most of the Java code, note that we need information about java method argument strings for C
         out_java_trait = out_java_trait + self.hu_struct_file_prefix
+        if trait_doc_comment is not None:
+            out_java_trait += "/**\n * " + trait_doc_comment.replace("\n", "\n * ") + "\n */\n"
+        out_java_trait += "@SuppressWarnings(\"unchecked\") // We correctly assign various generic arrays\n"
         out_java_trait = out_java_trait + "public class " + struct_name.replace("LDK","") + " extends CommonBase {\n"
         out_java_trait = out_java_trait + "\tfinal bindings." + struct_name + " bindings_instance;\n"
         out_java_trait = out_java_trait + "\t" + struct_name.replace("LDK", "") + "(Object _dummy, long ptr) { super(ptr); bindings_instance = null; }\n"
@@ -533,6 +537,7 @@ import java.util.Arrays;
             if fn_line.fn_name != "free" and fn_line.fn_name != "clone":
                 out_java = out_java + "\t\t " + fn_line.ret_ty_info.java_ty + " " + fn_line.fn_name + "("
                 java_trait_constr = java_trait_constr + "\t\t\t@Override public " + fn_line.ret_ty_info.java_ty + " " + fn_line.fn_name + "("
+                out_java_trait += "\t\t/**\n\t\t * " + fn_line.docs.replace("\n", "\n\t\t * ") + "\n\t\t */\n"
                 out_java_trait = out_java_trait + "\t\t" + fn_line.ret_ty_info.java_hu_ty + " " + fn_line.fn_name + "("
 
                 for idx, arg_conv_info in enumerate(fn_line.args_ty):
@@ -753,13 +758,15 @@ import java.util.Arrays;
         base_conv = base_conv + "\t" + ty_info.rust_obj + "_JCalls_clone(" + ty_info.var_name + "_conv.this_arg);\n}"
         return base_conv
 
-    def map_complex_enum(self, struct_name, variant_list, camel_to_snake):
+    def map_complex_enum(self, struct_name, variant_list, camel_to_snake, enum_doc_comment):
         java_hu_type = struct_name.replace("LDK", "")
         out_java_enum = ""
         out_java = ""
         out_c = ""
 
         out_java_enum += (self.hu_struct_file_prefix)
+        out_java_enum += "\n/**\n * " + enum_doc_comment.replace("\n", "\n * ") + "\n */\n"
+        out_java_enum += "@SuppressWarnings(\"unchecked\") // We correctly assign various generic arrays\n"
         out_java_enum += ("public class " + java_hu_type + " extends CommonBase {\n")
         out_java_enum += ("\tprivate " + java_hu_type + "(Object _dummy, long ptr) { super(ptr); }\n")
         out_java_enum += ("\t@Override @SuppressWarnings(\"deprecation\")\n")
@@ -837,9 +844,11 @@ import java.util.Arrays;
         out_java_enum += ("}\n")
         return (out_java, out_java_enum, out_c)
 
-    def map_opaque_struct(self, struct_name):
+    def map_opaque_struct(self, struct_name, struct_doc_comment):
         out_opaque_struct_human = ""
         out_opaque_struct_human += self.hu_struct_file_prefix
+        out_opaque_struct_human += "\n/**\n * " + struct_doc_comment.replace("\n", "\n * ") + "\n */\n"
+        out_opaque_struct_human += "@SuppressWarnings(\"unchecked\") // We correctly assign various generic arrays\n"
         out_opaque_struct_human += ("public class " + struct_name.replace("LDK","") + " extends CommonBase")
         if struct_name.startswith("LDKLocked"):
             out_opaque_struct_human += (" implements AutoCloseable")
@@ -856,7 +865,7 @@ import java.util.Arrays;
         return out_opaque_struct_human
 
 
-    def map_function(self, argument_types, c_call_string, method_name, return_type_info, struct_meth, default_constructor_args, takes_self, args_known, type_mapping_generator):
+    def map_function(self, argument_types, c_call_string, method_name, return_type_info, struct_meth, default_constructor_args, takes_self, args_known, type_mapping_generator, doc_comment):
         out_java = ""
         out_c = ""
         out_java_struct = None
@@ -884,6 +893,8 @@ import java.util.Arrays;
             out_java_struct += ("\t// Skipped " + method_name + "\n")
         else:
             meth_n = method_name[len(struct_meth) + 1:]
+            if doc_comment is not None:
+                out_java_struct += "\t/**\n\t * " + doc_comment.replace("\n", "\n\t * ") + "\n\t */\n"
             if not takes_self:
                 out_java_struct += (
                     "\tpublic static " + return_type_info.java_hu_ty + " constructor_" + meth_n + "(")

diff --git a/typescript_strings.py b/typescript_strings.py
index 2bfd240bd22b8846f6cb5ffe00d74569c0adab6e..a3c706ecafc98bf22eb893c41eeb8cf53fcd69db 100644 (file)
--- a/typescript_strings.py
+++ b/typescript_strings.py
@@ -436,7 +436,7 @@ const decodeString = (stringPointer, free = true) => {
     def init_str(self):
         return ""
 
-    def native_c_unitary_enum_map(self, struct_name, variants):
+    def native_c_unitary_enum_map(self, struct_name, variants, enum_doc_comment):
         out_c = "static inline " + struct_name + " " + struct_name + "_from_js(int32_t ord) {\n"
         out_c = out_c + "\tswitch (ord) {\n"
         ord_v = 0
@@ -483,7 +483,7 @@ const decodeString = (stringPointer, free = true) => {
             ret = ret + "; (void) " + param
         return ret
 
-    def native_c_map_trait(self, struct_name, field_var_conversions, field_function_lines):
+    def native_c_map_trait(self, struct_name, field_var_conversions, field_function_lines, trait_doc_comment):
         out_typescript_bindings = "\n\n\n// OUT_TYPESCRIPT_BINDINGS :: MAP_TRAIT :: START\n\n"
 
         constructor_arguments = ""
@@ -790,7 +790,7 @@ const decodeString = (stringPointer, free = true) => {
     def trait_struct_inc_refcnt(self, ty_info):
         return ""
 
-    def map_complex_enum(self, struct_name, variant_list, camel_to_snake):
+    def map_complex_enum(self, struct_name, variant_list, camel_to_snake, enum_doc_comment):
         java_hu_type = struct_name.replace("LDK", "")
 
         out_java_enum = ""
@@ -867,7 +867,7 @@ const decodeString = (stringPointer, free = true) => {
         out_java_enum += (java_hu_subclasses)
         return (out_java, out_java_enum, out_c)
 
-    def map_opaque_struct(self, struct_name):
+    def map_opaque_struct(self, struct_name, struct_doc_comment):
         implementations = ""
         method_header = ""
         if struct_name.startswith("LDKLocked"):
@@ -897,7 +897,7 @@ const decodeString = (stringPointer, free = true) => {
 """
         return out_opaque_struct_human
 
-    def map_function(self, argument_types, c_call_string, method_name, return_type_info, struct_meth, default_constructor_args, takes_self, args_known, type_mapping_generator):
+    def map_function(self, argument_types, c_call_string, method_name, return_type_info, struct_meth, default_constructor_args, takes_self, args_known, type_mapping_generator, doc_comment):
         out_java = ""
         out_c = ""
         out_java_struct = None