From: Matt Corallo Date: Sun, 7 Mar 2021 19:14:29 +0000 (-0500) Subject: Add struct and enum doc comments in Java X-Git-Tag: v0.0.98~12^2~4 X-Git-Url: http://git.bitcoin.ninja/?a=commitdiff_plain;h=51b99938ad39a1215696f57e37c8ee79307c1086;p=ldk-java Add struct and enum doc comments in Java --- diff --git a/bindingstypes.py b/bindingstypes.py index 66f34a58..aab05250 100644 --- 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 ca88a3aa..124a76ba 100755 --- 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 4b2ae77f..d827da9e 100644 --- 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 2bfd240b..a3c706ec 100644 --- 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