From 73c3ca7cb59a5e6e6fe72ea82d08a98f6d449b6e Mon Sep 17 00:00:00 2001 From: Alejandro Cabeza Romero Date: Fri, 24 Apr 2026 13:37:55 +0200 Subject: [PATCH] Add missing docs. --- rust/logos-blockchain-circuits-types/src/ffi/bytes.rs | 6 ++++++ rust/logos-blockchain-circuits-types/src/ffi/mod.rs | 5 +++++ rust/logos-blockchain-circuits-types/src/ffi/status.rs | 6 +++--- .../src/ffi/witness_input.rs | 5 +++++ rust/logos-blockchain-circuits-types/src/lib.rs | 6 ++++++ rust/logos-blockchain-circuits-types/src/native/bytes.rs | 6 +++++- rust/logos-blockchain-circuits-types/src/native/mod.rs | 4 ++++ rust/logos-blockchain-circuits-types/src/native/status.rs | 1 + .../src/native/witness_input.rs | 8 +++++++- 9 files changed, 42 insertions(+), 5 deletions(-) diff --git a/rust/logos-blockchain-circuits-types/src/ffi/bytes.rs b/rust/logos-blockchain-circuits-types/src/ffi/bytes.rs index 9de4a08..046257d 100644 --- a/rust/logos-blockchain-circuits-types/src/ffi/bytes.rs +++ b/rust/logos-blockchain-circuits-types/src/ffi/bytes.rs @@ -8,7 +8,13 @@ mod inner { } } +/// Owned byte buffer returned by the C witness generator functions. +/// +/// The inner `data` pointer must be null-initialized. It's heap-allocated by the C side and must be +/// freed with [`free_bytes`] after use. pub type Bytes = inner::Buffer<*mut u8>; + +/// Read-only byte slice passed into the C witness generator functions. pub type ConstBytes = inner::Buffer<*const u8>; /// Frees the data buffer inside a [`Bytes`] struct allocated by the C API. diff --git a/rust/logos-blockchain-circuits-types/src/ffi/mod.rs b/rust/logos-blockchain-circuits-types/src/ffi/mod.rs index 1ab276d..9176c20 100644 --- a/rust/logos-blockchain-circuits-types/src/ffi/mod.rs +++ b/rust/logos-blockchain-circuits-types/src/ffi/mod.rs @@ -1,3 +1,8 @@ +//! Raw `#[repr(C)]` types that mirror the C witness generator API. +//! +//! These types map directly to the C header structs and are used at the FFI boundary. Prefer the +//! wrappers in [`crate::native`] for ordinary Rust code. + pub mod status; pub mod bytes; pub mod witness_input; diff --git a/rust/logos-blockchain-circuits-types/src/ffi/status.rs b/rust/logos-blockchain-circuits-types/src/ffi/status.rs index 627c08b..746dfaf 100644 --- a/rust/logos-blockchain-circuits-types/src/ffi/status.rs +++ b/rust/logos-blockchain-circuits-types/src/ffi/status.rs @@ -1,7 +1,7 @@ use std::ffi::c_char; +/// Status codes for C API functions. #[repr(C)] -#[derive(Debug, PartialEq)] pub enum Code { Ok = 0, DynError = 1, @@ -11,7 +11,7 @@ pub enum Code { impl Code { pub fn is_ok(&self) -> bool { - self == &Code::Ok + matches!(self, Code::Ok) } pub fn is_error(&self) -> bool { @@ -19,8 +19,8 @@ impl Code { } } +/// Status reporting structure for C API functions. #[repr(C)] -#[derive(Debug)] pub struct Status { pub code: Code, pub message: [c_char; 256], diff --git a/rust/logos-blockchain-circuits-types/src/ffi/witness_input.rs b/rust/logos-blockchain-circuits-types/src/ffi/witness_input.rs index 431f959..12741bd 100644 --- a/rust/logos-blockchain-circuits-types/src/ffi/witness_input.rs +++ b/rust/logos-blockchain-circuits-types/src/ffi/witness_input.rs @@ -1,8 +1,13 @@ use std::ffi::c_char; use crate::ffi::ConstBytes; +/// Input to a witness generator function. +/// +/// Both pointers must remain valid for the duration of the C call. #[repr(C)] pub struct WitnessInput { + /// The circuit data file contents. pub dat: ConstBytes, + /// Null-terminated JSON string containing the circuit inputs. pub inputs_json: *const c_char, } diff --git a/rust/logos-blockchain-circuits-types/src/lib.rs b/rust/logos-blockchain-circuits-types/src/lib.rs index cd9165f..ddbf2af 100644 --- a/rust/logos-blockchain-circuits-types/src/lib.rs +++ b/rust/logos-blockchain-circuits-types/src/lib.rs @@ -1,2 +1,8 @@ +//! Raw FFI types and Rust-safe wrappers for the witness generator C API. +//! +//! The [`ffi`] module contains `#[repr(C)]` types that mirror the C headers directly. The +//! [`native`] module re-exposes those through idiomatic Rust types that own their memory and +//! convert FFI return values into [`Result`]s. + pub mod native; pub mod ffi; diff --git a/rust/logos-blockchain-circuits-types/src/native/bytes.rs b/rust/logos-blockchain-circuits-types/src/native/bytes.rs index f905a0b..53251d4 100644 --- a/rust/logos-blockchain-circuits-types/src/native/bytes.rs +++ b/rust/logos-blockchain-circuits-types/src/native/bytes.rs @@ -1,5 +1,9 @@ use crate::ffi; +/// Byte buffer +/// +/// When constructing from [`From`], it takes ownership of the underlying value and +/// frees it. pub struct Bytes(Vec); impl Bytes { @@ -7,7 +11,7 @@ impl Bytes { pub fn into_inner(self) -> Vec { self.0 } - + #[must_use] pub fn as_slice(&self) -> &[u8] { &self.0 diff --git a/rust/logos-blockchain-circuits-types/src/native/mod.rs b/rust/logos-blockchain-circuits-types/src/native/mod.rs index f035abb..0152c1f 100644 --- a/rust/logos-blockchain-circuits-types/src/native/mod.rs +++ b/rust/logos-blockchain-circuits-types/src/native/mod.rs @@ -1,3 +1,7 @@ +//! Rust-safe wrappers around the FFI types. +//! +//! Use them in preference to the types in [`crate::ffi`]. + pub mod bytes; pub mod status; pub mod witness_input; diff --git a/rust/logos-blockchain-circuits-types/src/native/status.rs b/rust/logos-blockchain-circuits-types/src/native/status.rs index 5a72315..d2dddc7 100644 --- a/rust/logos-blockchain-circuits-types/src/native/status.rs +++ b/rust/logos-blockchain-circuits-types/src/native/status.rs @@ -5,6 +5,7 @@ use crate::ffi::status::Code as FfiStatusCode; pub type DynError = Box; pub type Result = std::result::Result; +/// Error returned when a witness generator call does not succeed. #[derive(Debug, Error)] pub enum Error { #[error("Invalid input")] diff --git a/rust/logos-blockchain-circuits-types/src/native/witness_input.rs b/rust/logos-blockchain-circuits-types/src/native/witness_input.rs index 562328a..3f6f7be 100644 --- a/rust/logos-blockchain-circuits-types/src/native/witness_input.rs +++ b/rust/logos-blockchain-circuits-types/src/native/witness_input.rs @@ -1,8 +1,11 @@ use std::ffi::{c_char, CString, NulError}; use crate::ffi; +/// Input for witness generators pub struct WitnessInput { + /// The circuit's dat file contents. dat: Vec, + /// The JSON string containing the circuit inputs. inputs_json: String, } @@ -12,6 +15,9 @@ impl WitnessInput { Self { dat, inputs_json } } + /// Borrows this value as a temporary FFI-compatible view. + /// + /// Returns an error if `inputs_json` contains an interior null byte. pub fn as_ffi(&'_ self) -> Result, NulError> { WitnessInputFfiGuard::new(self) } @@ -29,7 +35,7 @@ pub struct WitnessInputFfiGuard<'a> { impl<'a> WitnessInputFfiGuard<'a> { fn new(inner: &'a WitnessInput) -> Result { let dat = ffi::ConstBytes { data: inner.dat.as_ptr(), size: inner.dat.len() }; - let inputs_json = CString::new(inner.inputs_json.clone())?.into_raw(); + let inputs_json = CString::new(inner.inputs_json.clone())?.into_raw(); // TODO CLEANER? let ffi = ffi::WitnessInput { dat, inputs_json }; Ok(Self { ffi,