From dae4ad72afe63fecd1e2d343e902eba9f83db1cf Mon Sep 17 00:00:00 2001
From: RJ Rybarczyk <rj@rybar.tech>
Date: Tue, 8 Oct 2024 16:56:22 -0400
Subject: [PATCH] Update sv2 header w alphabetical Error enum

---
 protocols/v2/sv2-ffi/sv2.h | 36 ++++++++++++++++++++++++------------
 1 file changed, 24 insertions(+), 12 deletions(-)

diff --git a/protocols/v2/sv2-ffi/sv2.h b/protocols/v2/sv2-ffi/sv2.h
index 8c941fff9b..8ea99dd691 100644
--- a/protocols/v2/sv2-ffi/sv2.h
+++ b/protocols/v2/sv2-ffi/sv2.h
@@ -430,24 +430,32 @@ void free_submit_solution(CSubmitSolution s);
 #include <ostream>
 #include <new>
 
+/// C-compatible enumeration of possible errors in the `codec_sv2` module.
+///
+/// This enum mirrors the [`Error`] enum but is designed to be used in C code through FFI. It
+/// represents the same set of errors as [`Error`], making them accessible to C programs.
 struct CError {
   enum class Tag {
-    /// Errors from the `binary_sv2` crate
+    /// AEAD (`snow`) error in the Noise protocol.
+    AeadError,
+    /// Binary Sv2 data format error.
     BinarySv2Error,
-    /// Errors from the `framing_sv2` crate
+    /// Framing Sv2 error.
+    FramingError,
+    /// Framing Sv2 error.
     FramingSv2Error,
-    /// Errors if there are missing bytes in the Noise protocol
+    /// Invalid step for initiator in the Noise protocol.
+    InvalidStepForInitiator,
+    /// Invalid step for responder in the Noise protocol.
+    InvalidStepForResponder,
+    /// Missing bytes in the Noise protocol.
     MissingBytes,
-    /// Errors from the `noise_sv2` crate
+    /// Sv2 Noise protocol error.
     NoiseSv2Error,
-    /// `snow` errors
-    AeadError,
-    /// Error if Noise protocol state is not as expected
-    UnexpectedNoiseState,
-    InvalidStepForResponder,
-    InvalidStepForInitiator,
+    /// Noise protocol is not in the expected handshake state.
     NotInHandShakeState,
-    FramingError,
+    /// Unexpected state in the Noise protocol.
+    UnexpectedNoiseState,
   };
 
   struct MissingBytes_Body {
@@ -462,7 +470,11 @@ struct CError {
 
 extern "C" {
 
-/// Here only to force cbindgen to create header for CError
+/// Force `cbindgen` to create a header for [`CError`].
+///
+/// It ensures that [`CError`] is included in the generated C header file. This function is not meant
+/// to be called and will panic if called. Its only purpose is to make [`CError`] visible to
+/// `cbindgen`.
 CError export_cerror();
 
 } // extern "C"