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 e97fb65e88e4c0a58dfcf82e959e48515aecbc9f..5072f8ab06db481ae6e2954aa2dd4f3723d50b7f 100644 (file)
--- 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 {