huskies: merge 854

crates/bft-json-crdt/src/debug.rs

@@ -1,3 +1,9 @@
+//! Debug helpers and the [`DebugView`] trait for rendering CRDT internals.
+//!
+//! Most items in this module are no-ops in release builds. They are activated by
+//! the `logging-base`, `logging-json`, and `logging-list` Cargo features so that
+//! debug output can be toggled without changing production code.
+
 use crate::{
     json_crdt::{BaseCrdt, CrdtNode, SignedOp},
     keypair::SignedDigest,
@@ -37,6 +43,7 @@ fn display_op_id<T: CrdtNode>(op: &Op<T>) -> String {
     )
 }
 
+/// Log a type-mismatch warning when deserialising a JSON value into a CRDT node fails.
 pub fn debug_type_mismatch(_msg: String) {
     #[cfg(feature = "logging-base")]
     {
@@ -44,6 +51,7 @@ pub fn debug_type_mismatch(_msg: String) {
     }
 }
 
+/// Log a path-mismatch warning when an operation's path does not match the CRDT's path.
 pub fn debug_path_mismatch(_our_path: Vec<PathSegment>, _op_path: Vec<PathSegment>) {
     #[cfg(feature = "logging-base")]
     {
@@ -56,6 +64,7 @@ pub fn debug_path_mismatch(_our_path: Vec<PathSegment>, _op_path: Vec<PathSegmen
     }
 }
 
+/// Log a warning when an operation is applied to a primitive (terminal) CRDT node.
 pub fn debug_op_on_primitive(_op_path: Vec<PathSegment>) {
     #[cfg(feature = "logging-base")]
     {
@@ -79,16 +88,20 @@ fn display_author(author: AuthorId) -> String {
         .to_string()
 }
 
+/// Render CRDT state as an indented human-readable string for debugging.
 pub trait DebugView {
+    /// Return a multi-line debug string for this CRDT node, indented by `indent` spaces.
     fn debug_view(&self, indent: usize) -> String;
 }
 
 impl<T: CrdtNode + DebugView> BaseCrdt<T> {
+    /// Print the current document state as an indented debug tree (no-op in release builds).
     pub fn debug_view(&self) {
         #[cfg(feature = "logging-json")]
         println!("document is now:\n{}", self.doc.debug_view(0));
     }
 
+    /// Log an attempt to apply `op` before the result is known (no-op in release builds).
     pub fn log_try_apply(&self, _op: &SignedOp) {
         #[cfg(feature = "logging-json")]
         println!(
@@ -99,6 +112,7 @@ impl<T: CrdtNode + DebugView> BaseCrdt<T> {
         );
     }
 
+    /// Log a signature-digest verification failure for `op` (no-op in release builds).
     pub fn debug_digest_failure(&self, _op: SignedOp) {
         #[cfg(feature = "logging-json")]
         println!(
@@ -108,6 +122,7 @@ impl<T: CrdtNode + DebugView> BaseCrdt<T> {
         );
     }
 
+    /// Log that a causal dependency identified by `missing` has not yet been received.
     pub fn log_missing_causal_dep(&self, _missing: &SignedDigest) {
         #[cfg(feature = "logging-json")]
         println!(
@@ -117,6 +132,7 @@ impl<T: CrdtNode + DebugView> BaseCrdt<T> {
         );
     }
 
+    /// Log that `op` is about to be integrated into the document (no-op in release builds).
     pub fn log_actually_apply(&self, _op: &SignedOp) {
         #[cfg(feature = "logging-json")]
         {
@@ -133,6 +149,7 @@ impl<T> Op<T>
 where
     T: CrdtNode,
 {
+    /// Log an operation hash verification failure showing expected and computed IDs.
     pub fn debug_hash_failure(&self) {
         #[cfg(feature = "logging-base")]
         {
@@ -191,6 +208,7 @@ impl<T> ListCrdt<T>
 where
     T: CrdtNode,
 {
+    /// Print the full operation log as a tree, optionally highlighting one operation (no-op in release builds).
     pub fn log_ops(&self, _highlight: Option<OpId>) {
         #[cfg(feature = "logging-list")]
         {
@@ -289,6 +307,7 @@ where
         }
     }
 
+    /// Log the insert or delete being performed for `op` (no-op in release builds).
     pub fn log_apply(&self, _op: &Op<T>) {
         #[cfg(feature = "logging-list")]
         {