Add missing docs.

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.

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;

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],

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,
 }

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;

rust/logos-blockchain-circuits-types/src/native/bytes.rs

@@ -1,5 +1,9 @@
 use crate::ffi;
 
+/// Byte buffer
+///
+/// When constructing from [`From<ffi::Bytes>`], it takes ownership of the underlying value and
+/// frees it.
 pub struct Bytes(Vec<u8>);
 
 impl Bytes {
@@ -7,7 +11,7 @@ impl Bytes {
     pub fn into_inner(self) -> Vec<u8> {
         self.0
     }
-    
+
     #[must_use]
     pub fn as_slice(&self) -> &[u8] {
         &self.0

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;

rust/logos-blockchain-circuits-types/src/native/status.rs

@@ -5,6 +5,7 @@ use crate::ffi::status::Code as FfiStatusCode;
 pub type DynError = Box<dyn std::error::Error + Send + Sync>;
 pub type Result<T> = std::result::Result<T, Error>;
 
+/// Error returned when a witness generator call does not succeed.
 #[derive(Debug, Error)]
 pub enum Error {
     #[error("Invalid input")]

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<u8>,
+    /// 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<WitnessInputFfiGuard<'_>, NulError> {
         WitnessInputFfiGuard::new(self)
     }
@@ -29,7 +35,7 @@ pub struct WitnessInputFfiGuard<'a> {
 impl<'a> WitnessInputFfiGuard<'a> {
     fn new(inner: &'a WitnessInput) -> Result<Self, NulError> {
         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,