From 3ac7fd4b660c2f2a897efbd5372c82a89bab0e53 Mon Sep 17 00:00:00 2001 From: Matt Corallo Date: Mon, 29 Mar 2021 14:40:22 -0400 Subject: [PATCH] Add missing documentation to c_types module contents --- c-bindings-gen/src/blocks.rs | 38 +++++++++++++++++ lightning-c-bindings/src/bitcoin/mod.rs | 2 + lightning-c-bindings/src/bitcoin/network.rs | 7 +++ lightning-c-bindings/src/c_types/mod.rs | 47 +++++++++++++++++++-- 4 files changed, 90 insertions(+), 4 deletions(-) diff --git a/c-bindings-gen/src/blocks.rs b/c-bindings-gen/src/blocks.rs index 4f957ce..bbb41e0 100644 --- a/c-bindings-gen/src/blocks.rs +++ b/c-bindings-gen/src/blocks.rs @@ -43,14 +43,19 @@ pub fn write_cpp_wrapper(cpp_header_file: &mut File, ty: &str, has_destructor: b /// Writes out a C-callable concrete Result struct and utility methods pub fn write_result_block(w: &mut W, mangled_container: &str, ok_type: &str, err_type: &str, clonable: bool) { writeln!(w, "#[repr(C)]").unwrap(); + writeln!(w, "/// The contents of {}", mangled_container).unwrap(); writeln!(w, "pub union {}Ptr {{", mangled_container).unwrap(); if ok_type != "()" { + writeln!(w, "\t/// A pointer to the contents in the success state.").unwrap(); + writeln!(w, "\t/// Reading from this pointer when `result_ok` is not set is undefined.").unwrap(); writeln!(w, "\tpub result: *mut {},", ok_type).unwrap(); } else { writeln!(w, "\t/// Note that this value is always NULL, as there are no contents in the OK variant").unwrap(); writeln!(w, "\tpub result: *mut std::ffi::c_void,").unwrap(); } if err_type != "()" { + writeln!(w, "\t/// A pointer to the contents in the error state.").unwrap(); + writeln!(w, "\t/// Reading from this pointer when `result_ok` is set is undefined.").unwrap(); writeln!(w, "\tpub err: *mut {},", err_type).unwrap(); } else { writeln!(w, "\t/// Note that this value is always NULL, as there are no contents in the Err variant").unwrap(); @@ -58,15 +63,23 @@ pub fn write_result_block(w: &mut W, mangled_container: &str, } writeln!(w, "}}").unwrap(); writeln!(w, "#[repr(C)]").unwrap(); + writeln!(w, "/// A {} represents the result of a fallible operation,", mangled_container).unwrap(); + writeln!(w, "/// containing a {} on success and a {} on failure.", ok_type, err_type).unwrap(); + writeln!(w, "/// `result_ok` indicates the overall state, and the contents are provided via `contents`.").unwrap(); writeln!(w, "pub struct {} {{", mangled_container).unwrap(); + writeln!(w, "\t/// The contents of this {}, accessible via either", mangled_container).unwrap(); + writeln!(w, "\t/// `err` or `result` depending on the state of `result_ok`.").unwrap(); writeln!(w, "\tpub contents: {}Ptr,", mangled_container).unwrap(); + writeln!(w, "\t/// Whether this {} represents a success state.", mangled_container).unwrap(); writeln!(w, "\tpub result_ok: bool,").unwrap(); writeln!(w, "}}").unwrap(); writeln!(w, "#[no_mangle]").unwrap(); if ok_type != "()" { + writeln!(w, "/// Creates a new {} in the success state.", mangled_container).unwrap(); writeln!(w, "pub extern \"C\" fn {}_ok(o: {}) -> {} {{", mangled_container, ok_type, mangled_container).unwrap(); } else { + writeln!(w, "/// Creates a new {} in the success state.", mangled_container).unwrap(); writeln!(w, "pub extern \"C\" fn {}_ok() -> {} {{", mangled_container, mangled_container).unwrap(); } writeln!(w, "\t{} {{", mangled_container).unwrap(); @@ -83,8 +96,10 @@ pub fn write_result_block(w: &mut W, mangled_container: &str, writeln!(w, "#[no_mangle]").unwrap(); if err_type != "()" { + writeln!(w, "/// Creates a new {} in the error state.", mangled_container).unwrap(); writeln!(w, "pub extern \"C\" fn {}_err(e: {}) -> {} {{", mangled_container, err_type, mangled_container).unwrap(); } else { + writeln!(w, "/// Creates a new {} in the error state.", mangled_container).unwrap(); writeln!(w, "pub extern \"C\" fn {}_err() -> {} {{", mangled_container, mangled_container).unwrap(); } writeln!(w, "\t{} {{", mangled_container).unwrap(); @@ -100,6 +115,7 @@ pub fn write_result_block(w: &mut W, mangled_container: &str, writeln!(w, "}}").unwrap(); writeln!(w, "#[no_mangle]").unwrap(); + writeln!(w, "/// Frees any resources used by the {}.", mangled_container).unwrap(); writeln!(w, "pub extern \"C\" fn {}_free(_res: {}) {{ }}", mangled_container, mangled_container).unwrap(); writeln!(w, "impl Drop for {} {{", mangled_container).unwrap(); writeln!(w, "\tfn drop(&mut self) {{").unwrap(); @@ -176,6 +192,8 @@ pub fn write_result_block(w: &mut W, mangled_container: &str, writeln!(w, "\t}}").unwrap(); writeln!(w, "}}").unwrap(); writeln!(w, "#[no_mangle]").unwrap(); + writeln!(w, "/// Creates a new {} which has the same data as `orig`", mangled_container).unwrap(); + writeln!(w, "/// but with all dynamically-allocated buffers duplicated in new buffers.").unwrap(); writeln!(w, "pub extern \"C\" fn {}_clone(orig: &{}) -> {} {{ orig.clone() }}", mangled_container, mangled_container, mangled_container).unwrap(); } } @@ -183,8 +201,13 @@ pub fn write_result_block(w: &mut W, mangled_container: &str, /// Writes out a C-callable concrete Vec struct and utility methods pub fn write_vec_block(w: &mut W, mangled_container: &str, inner_type: &str, clonable: bool) { writeln!(w, "#[repr(C)]").unwrap(); + writeln!(w, "/// A dynamically-allocated array of {}s of arbitrary size.", inner_type).unwrap(); + writeln!(w, "/// This corresponds to std::vector in C++").unwrap(); writeln!(w, "pub struct {} {{", mangled_container).unwrap(); + writeln!(w, "\t/// The elements in the array.").unwrap(); + writeln!(w, "\t/// If datalen is non-0 this must be a valid, non-NULL pointer allocated by malloc().").unwrap(); writeln!(w, "\tpub data: *mut {},", inner_type).unwrap(); + writeln!(w, "\t/// The number of elements pointed to by `data`.").unwrap(); writeln!(w, "\tpub datalen: usize").unwrap(); writeln!(w, "}}").unwrap(); @@ -210,6 +233,7 @@ pub fn write_vec_block(w: &mut W, mangled_container: &str, in writeln!(w, "}}").unwrap(); writeln!(w, "#[no_mangle]").unwrap(); + writeln!(w, "/// Frees the buffer pointed to by `data` if `datalen` is non-0.").unwrap(); writeln!(w, "pub extern \"C\" fn {}_free(_res: {}) {{ }}", mangled_container, mangled_container).unwrap(); writeln!(w, "impl Drop for {} {{", mangled_container).unwrap(); writeln!(w, "\tfn drop(&mut self) {{").unwrap(); @@ -232,8 +256,10 @@ pub fn write_vec_block(w: &mut W, mangled_container: &str, in /// Writes out a C-callable concrete (A, B, ...) struct and utility methods pub fn write_tuple_block(w: &mut W, mangled_container: &str, types: &[String], clonable: bool) { writeln!(w, "#[repr(C)]").unwrap(); + writeln!(w, "/// A tuple of {} elements. See the individual fields for the types contained.", types.len()).unwrap(); writeln!(w, "pub struct {} {{", mangled_container).unwrap(); for (idx, ty) in types.iter().enumerate() { + writeln!(w, "\t/// The element at position {}", idx).unwrap(); writeln!(w, "\tpub {}: {},", ('a' as u8 + idx as u8) as char, ty).unwrap(); } writeln!(w, "}}").unwrap(); @@ -275,9 +301,12 @@ pub fn write_tuple_block(w: &mut W, mangled_container: &str, writeln!(w, "\t}}").unwrap(); writeln!(w, "}}").unwrap(); writeln!(w, "#[no_mangle]").unwrap(); + writeln!(w, "/// Creates a new tuple which has the same data as `orig`").unwrap(); + writeln!(w, "/// but with all dynamically-allocated buffers duplicated in new buffers.").unwrap(); writeln!(w, "pub extern \"C\" fn {}_clone(orig: &{}) -> {} {{ orig.clone() }}", mangled_container, mangled_container, mangled_container).unwrap(); } + writeln!(w, "/// Creates a new {} from the contained elements.", mangled_container).unwrap(); write!(w, "#[no_mangle]\npub extern \"C\" fn {}_new(", mangled_container).unwrap(); for (idx, gen) in types.iter().enumerate() { write!(w, "{}{}: ", if idx != 0 { ", " } else { "" }, ('a' as u8 + idx as u8) as char).unwrap(); @@ -292,6 +321,7 @@ pub fn write_tuple_block(w: &mut W, mangled_container: &str, writeln!(w, "}}\n}}\n").unwrap(); writeln!(w, "#[no_mangle]").unwrap(); + writeln!(w, "/// Frees any resources used by the {}.", mangled_container).unwrap(); writeln!(w, "pub extern \"C\" fn {}_free(_res: {}) {{ }}", mangled_container, mangled_container).unwrap(); } @@ -301,8 +331,11 @@ pub fn write_option_block(w: &mut W, mangled_container: &str, if clonable { writeln!(w, "#[derive(Clone)]").unwrap(); } + writeln!(w, "/// An enum which can either contain a {} or not", inner_type).unwrap(); writeln!(w, "pub enum {} {{", mangled_container).unwrap(); + writeln!(w, "\t/// When we're in this state, this {} contains a {}", mangled_container, inner_type).unwrap(); writeln!(w, "\tSome({}),", inner_type).unwrap(); + writeln!(w, "\t/// When we're in this state, this {} contains nothing", mangled_container).unwrap(); writeln!(w, "\tNone").unwrap(); writeln!(w, "}}").unwrap(); @@ -316,19 +349,24 @@ pub fn write_option_block(w: &mut W, mangled_container: &str, writeln!(w, "}}").unwrap(); writeln!(w, "#[no_mangle]").unwrap(); + writeln!(w, "/// Constructs a new {} containing a {}", mangled_container, inner_type).unwrap(); writeln!(w, "pub extern \"C\" fn {}_some(o: {}) -> {} {{", mangled_container, inner_type, mangled_container).unwrap(); writeln!(w, "\t{}::Some(o)", mangled_container).unwrap(); writeln!(w, "}}").unwrap(); writeln!(w, "#[no_mangle]").unwrap(); + writeln!(w, "/// Constructs a new {} containing nothing", mangled_container).unwrap(); writeln!(w, "pub extern \"C\" fn {}_none() -> {} {{", mangled_container, mangled_container).unwrap(); writeln!(w, "\t{}::None", mangled_container).unwrap(); writeln!(w, "}}").unwrap(); writeln!(w, "#[no_mangle]").unwrap(); + writeln!(w, "/// Frees any resources associated with the {}, if we are in the Some state", inner_type).unwrap(); writeln!(w, "pub extern \"C\" fn {}_free(_res: {}) {{ }}", mangled_container, mangled_container).unwrap(); if clonable { writeln!(w, "#[no_mangle]").unwrap(); + writeln!(w, "/// Creates a new {} which has the same data as `orig`", mangled_container).unwrap(); + writeln!(w, "/// but with all dynamically-allocated buffers duplicated in new buffers.").unwrap(); writeln!(w, "pub extern \"C\" fn {}_clone(orig: &{}) -> {} {{ orig.clone() }}", mangled_container, mangled_container, mangled_container).unwrap(); } } diff --git a/lightning-c-bindings/src/bitcoin/mod.rs b/lightning-c-bindings/src/bitcoin/mod.rs index a61610b..5b309bb 100644 --- a/lightning-c-bindings/src/bitcoin/mod.rs +++ b/lightning-c-bindings/src/bitcoin/mod.rs @@ -1 +1,3 @@ +//! C-mapped versions of items from rust-bitcoin + pub mod network; diff --git a/lightning-c-bindings/src/bitcoin/network.rs b/lightning-c-bindings/src/bitcoin/network.rs index 52cb2ce..02052e8 100644 --- a/lightning-c-bindings/src/bitcoin/network.rs +++ b/lightning-c-bindings/src/bitcoin/network.rs @@ -1,10 +1,17 @@ +//! A C-mapped version fo bitcoin::network::constants::Network + use bitcoin::network::constants::Network as BitcoinNetwork; #[repr(C)] +/// An enum representing the possible Bitcoin or test networks which we can run on pub enum Network { + /// The main Bitcoin blockchain. Bitcoin, + /// The testnet3 blockchain. Testnet, + /// A local test blockchain. Regtest, + /// A blockchain on which blocks are signed instead of mined. Signet, } diff --git a/lightning-c-bindings/src/c_types/mod.rs b/lightning-c-bindings/src/c_types/mod.rs index 0a96f3e..57b6dcd 100644 --- a/lightning-c-bindings/src/c_types/mod.rs +++ b/lightning-c-bindings/src/c_types/mod.rs @@ -1,3 +1,6 @@ +//! This module contains standard C-mapped types for types not in the original crate. + +/// Auto-generated C-mapped types for templated containers pub mod derived; use bitcoin::Script as BitcoinScript; @@ -12,7 +15,9 @@ use std::convert::TryInto; // Bindings need at least rustc 1.34 #[derive(Clone)] #[repr(C)] +/// Represents a valid secp256k1 public key serialized in "compressed form" as a 33 byte array. pub struct PublicKey { + /// The bytes of the public key pub compressed_form: [u8; 33], } impl PublicKey { @@ -29,7 +34,9 @@ impl PublicKey { } #[repr(C)] +/// Represents a valid secp256k1 secret key serialized as a 32 byte array. pub struct SecretKey { + /// The bytes of the secret key pub bytes: [u8; 32], } impl SecretKey { @@ -46,7 +53,9 @@ impl SecretKey { #[repr(C)] #[derive(Clone)] +/// Represents a secp256k1 signature serialized as two 32-byte numbers pub struct Signature { + /// The bytes of the signature in "compact" form pub compact_form: [u8; 64], } impl Signature { @@ -64,15 +73,25 @@ impl Signature { } #[repr(C)] +/// Represents an error returned from libsecp256k1 during validation of some secp256k1 data pub enum Secp256k1Error { + /// Signature failed verification IncorrectSignature, + /// Badly sized message ("messages" are actually fixed-sized digests; see the MESSAGE_SIZE constant) InvalidMessage, + /// Bad public key InvalidPublicKey, + /// Bad signature InvalidSignature, + /// Bad secret key InvalidSecretKey, + /// Bad recovery id InvalidRecoveryId, + /// Invalid tweak for add_assign or mul_assign InvalidTweak, + /// tweak_add_check failed on an xonly public key TweakCheckFailed, + /// Didn't pass enough memory to context creation with preallocated memory NotEnoughMemory, } impl Secp256k1Error { @@ -106,9 +125,13 @@ impl Secp256k1Error { /// set. Similarly, while it may change in the future, all `Transaction`s you pass to Rust may have /// `data_is_owned` either set or unset at your discretion. pub struct Transaction { + /// The serialized transaction data. + /// /// This is non-const for your convenience, an object passed to Rust is never written to. pub data: *mut u8, + /// The length of the serialized transaction pub datalen: usize, + /// Whether the data pointed to by `data` should be freed or not. pub data_is_owned: bool, } impl Transaction { @@ -134,6 +157,7 @@ impl Drop for Transaction { } } #[no_mangle] +/// Frees the data buffer, if data_is_owned is set and datalen > 0. pub extern "C" fn Transaction_free(_res: Transaction) { } pub(crate) fn bitcoin_to_C_outpoint(outpoint: ::bitcoin::blockdata::transaction::OutPoint) -> crate::chain::transaction::OutPoint { @@ -145,7 +169,9 @@ pub(crate) fn bitcoin_to_C_outpoint(outpoint: ::bitcoin::blockdata::transaction: /// A transaction output including a scriptPubKey and value. /// This type *does* own its own memory, so must be free'd appropriately. pub struct TxOut { + /// The script_pubkey in this output pub script_pubkey: derived::CVec_u8Z, + /// The value, in satoshis, of this output pub value: u64, } @@ -164,13 +190,19 @@ impl TxOut { } } #[no_mangle] +/// Frees the data pointed to by script_pubkey. pub extern "C" fn TxOut_free(_res: TxOut) { } #[no_mangle] +/// Creates a new TxOut which has the same data as `orig` but with a new script buffer. pub extern "C" fn TxOut_clone(orig: &TxOut) -> TxOut { orig.clone() } #[repr(C)] +/// A "slice" referencing some byte array. This is simply a length-tagged pointer which does not +/// own the memory pointed to by data. pub struct u8slice { + /// A pointer to the byte buffer pub data: *const u8, + /// The number of bytes pointed to by `data`. pub datalen: usize } impl u8slice { @@ -191,6 +223,7 @@ impl u8slice { /// Arbitrary 32 bytes, which could represent one of a few different things. You probably want to /// look up the corresponding function in rust-lightning's docs. pub struct ThirtyTwoBytes { + /// The thirty-two bytes pub data: [u8; 32], } impl ThirtyTwoBytes { @@ -200,16 +233,20 @@ impl ThirtyTwoBytes { } #[repr(C)] -pub struct ThreeBytes { pub data: [u8; 3], } +/// A 3-byte byte array. +pub struct ThreeBytes { /** The three bytes */ pub data: [u8; 3], } #[derive(Clone)] #[repr(C)] -pub struct FourBytes { pub data: [u8; 4], } +/// A 4-byte byte array. +pub struct FourBytes { /** The four bytes */ pub data: [u8; 4], } #[derive(Clone)] #[repr(C)] -pub struct TenBytes { pub data: [u8; 10], } +/// A 10-byte byte array. +pub struct TenBytes { /** The ten bytes */ pub data: [u8; 10], } #[derive(Clone)] #[repr(C)] -pub struct SixteenBytes { pub data: [u8; 16], } +/// A 16-byte byte array. +pub struct SixteenBytes { /** The sixteen bytes */ pub data: [u8; 16], } pub(crate) struct VecWriter(pub Vec); impl lightning::util::ser::Writer for VecWriter { @@ -238,7 +275,9 @@ pub(crate) fn deserialize_obj_arg>(s /// A Rust str object, ie a reference to a UTF8-valid string. /// This is *not* null-terminated so cannot be used directly as a C string! pub struct Str { + /// A pointer to the string's bytes, in UTF8 encoding pub chars: *const u8, + /// The number of bytes (not characters!) pointed to by `chars` pub len: usize } impl Into for &'static str { -- 2.30.2