huskies: merge 854

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

@@ -1,3 +1,9 @@
+//! Core operation types for the BFT JSON CRDT.
+//!
+//! Defines [`Op`] (the fundamental unit of change), [`PathSegment`] (for
+//! addressing nested CRDTs), and [`SequenceNumber`] / [`OpId`] type aliases.
+//! Also provides hashing utilities used when computing operation identifiers.
+
 use crate::debug::{debug_path_mismatch, debug_type_mismatch};
 use crate::json_crdt::{CrdtNode, CrdtNodeFromValue, IntoCrdtNode, JsonValue, SignedOp};
 use crate::keypair::{sha256, AuthorId};
@@ -113,6 +119,7 @@ where
 
 /// Conversion from Op<Value> -> Op<T> given that T is a CRDT that can be created from a JSON value
 impl Op<JsonValue> {
+    /// Convert this `Op<JsonValue>` into an `Op<T>` by deserialising the content via `T::node_from`.
     pub fn into<T: CrdtNodeFromValue + CrdtNode>(self) -> Op<T> {
         let content = if let Some(inner_content) = self.content {
             match inner_content.into_node(self.id, self.path.clone()) {
@@ -141,10 +148,12 @@ impl<T> Op<T>
 where
     T: CrdtNode,
 {
+    /// Sign this operation with `keypair`, producing a [`SignedOp`] with no causal dependencies.
     pub fn sign(self, keypair: &Ed25519KeyPair) -> SignedOp {
         SignedOp::from_op(self, keypair, vec![])
     }
 
+    /// Sign this operation and attach explicit causal `dependencies`.
     pub fn sign_with_dependencies(
         self,
         keypair: &Ed25519KeyPair,
@@ -160,14 +169,17 @@ where
         )
     }
 
+    /// Return the [`AuthorId`] (Ed25519 public key) of the node that created this operation.
     pub fn author(&self) -> AuthorId {
         self.author
     }
 
+    /// Return the Lamport sequence number carried by this operation.
     pub fn sequence_num(&self) -> SequenceNumber {
         self.seq
     }
 
+    /// Construct a new operation, computing its [`OpId`] hash from the supplied fields.
     pub fn new(
         origin: OpId,
         author: AuthorId,