From: Matt Corallo <git@bluematt.me>
Date: Tue, 28 Jun 2022 02:14:20 +0000 (+0000)
Subject: Add a note in output documentation for fields with refs to opaques
X-Git-Url: http://git.bitcoin.ninja/index.cgi?p=ldk-c-bindings;a=commitdiff_plain;h=ef521e155d142222012acc4b33a41e13c0bda6ee

Add a note in output documentation for fields with refs to opaques

Because we (probably shouldn't, but do) map "opaque" structs with
an `is_owned` field instead of having a dedicated reference type,
fields which are a `Deref<Struct>` are simply mapped as
`OpaqueMappedStruct`. This is confusing for downstream `lightning.h`
consumers as they cannot differentiate between a field that expects
to own a `Struct` and one which expects to own a reference to it.

This is worked around here by adding documentation which can be
matched on, though ultimately structs should move towards full
ownership.
---

diff --git a/c-bindings-gen/src/blocks.rs b/c-bindings-gen/src/blocks.rs
index 15b3bab..84a971b 100644
--- a/c-bindings-gen/src/blocks.rs
+++ b/c-bindings-gen/src/blocks.rs
@@ -460,7 +460,7 @@ fn writeln_docs_impl<'a, W: std::io::Write, I>(w: &mut W, attrs: &[syn::Attribut
 			},
 		}
 	}
-	if let Some((types, generics, inp, outp, field)) = method_args_ret {
+	if let Some((types, generics, inp, outp, field_ty)) = method_args_ret {
 		let mut nullable_found = false;
 		for (name, inp) in inp {
 			if types.skip_arg(inp, generics) { continue; }
@@ -491,8 +491,13 @@ fn writeln_docs_impl<'a, W: std::io::Write, I>(w: &mut W, attrs: &[syn::Attribut
 			nullable_found = true;
 			writeln!(w, "{}/// Note that the return value (or a relevant inner pointer) may be NULL or all-0s to represent None", prefix).unwrap();
 		}
+		let field = field_ty.map(|ty| generics.resolve_type(ty));
 		if if let Some(syn::Type::Reference(syn::TypeReference { elem, .. })) = field {
 			if let syn::Type::Path(syn::TypePath { ref path, .. }) = &**elem {
+				let resolved_path = types.resolve_path(path, generics);
+				if types.crate_types.opaques.get(&resolved_path).is_some() {
+					writeln!(w, "{}/// Note that this field is expected to be a reference.", prefix).unwrap();
+				}
 				types.is_path_transparent_container(path, generics, true)
 			} else { false }
 		} else if let Some(syn::Type::Path(syn::TypePath { ref path, .. })) = field {