inline macro and rust-doc

protocols/v2/noise-sv2/src/handshake.rs

@@ -105,7 +105,7 @@ pub trait HandshakeOp<Cipher: AeadCipher>: CipherState<Cipher> {
     fn generate_key() -> Keypair {
         Self::generate_key_with_rng(&mut rand::thread_rng())
     }
-
+    #[inline]
     fn generate_key_with_rng<R: rand::Rng + ?Sized>(rng: &mut R) -> Keypair {
         let secp = Secp256k1::new();
         let (secret_key, _) = secp.generate_keypair(rng);

protocols/v2/noise-sv2/src/initiator.rs

@@ -172,6 +172,16 @@ impl Initiator {
     pub fn new(pk: Option<XOnlyPublicKey>) -> Box<Self> {
         Self::new_with_rng(pk, &mut rand::thread_rng())
     }
+
+    /// Creates a new [`Initiator`] instance with an optional responder public key and a custom
+    /// random number generator.
+    ///
+    /// If the responder public key is provided, the initiator uses this key to authenticate the
+    /// responder during the handshake. The initial initiator state is instantiated with the
+    /// ephemeral key pair and handshake hash.
+    ///
+    /// The custom random number generator is used to generate the ephemeral key pair.
+    #[inline]
     pub fn new_with_rng<R: rand::Rng + ?Sized>(
         pk: Option<XOnlyPublicKey>,
         rng: &mut R,
@@ -202,6 +212,18 @@ impl Initiator {
     pub fn from_raw_k(key: [u8; 32]) -> Result<Box<Self>, Error> {
         Self::from_raw_k_with_rng(key, &mut rand::thread_rng())
     }
+
+    /// Creates a new [`Initiator`] instance using a raw 32-byte public key and a custom random
+    /// number generator.
+    ///
+    /// Constructs a [`XOnlyPublicKey`] from the provided raw key slice and initializes a new
+    /// [`Initiator`] with the derived public key and the custom random number generator. If the
+    /// provided key cannot be converted into a valid [`XOnlyPublicKey`], an
+    /// [`Error::InvalidRawPublicKey`] error is returned.
+    ///
+    /// Typically used when the initiator is aware of the responder's public key in advance and
+    /// wants to use a custom random number generator.
+    #[inline]
     pub fn from_raw_k_with_rng<R: rand::Rng + ?Sized>(
         key: [u8; 32],
         rng: &mut R,
@@ -220,6 +242,17 @@ impl Initiator {
     pub fn without_pk() -> Result<Box<Self>, Error> {
         Self::without_pk_with_rng(&mut rand::thread_rng())
     }
+
+    /// Creates a new [`Initiator`] instance without a responder's public key and using a custom
+    /// random number generator.
+    ///
+    /// This function initializes an [`Initiator`] with a default empty state, without requiring the
+    /// responder's authority public key, ideal for scenarios where both parties are within the same
+    /// network. The custom random number generator is used to generate the ephemeral key pair,
+    /// ensuring unique and secure cryptographic materials for the handshake process. The
+    /// connection remains encrypted, even though the initiator does not validate the
+    /// responder's static key from a certificate. Returns an error if the initialization fails.
+    #[inline]
     pub fn without_pk_with_rng<R: rand::Rng + ?Sized>(rng: &mut R) -> Result<Box<Self>, Error> {
         Ok(Self::new_with_rng(None, rng))
     }

protocols/v2/noise-sv2/src/responder.rs

@@ -180,6 +180,17 @@ impl Responder {
     pub fn new(a: Keypair, cert_validity: u32) -> Box<Self> {
         Self::new_with_rng(a, cert_validity, &mut rand::thread_rng())
     }
+
+    /// Creates a new [`Responder`] instance with the provided authority keypair, certificate
+    /// validity, and a custom random number generator.
+    ///
+    /// Constructs a new [`Responder`] with the necessary cryptographic state for the Noise NX
+    /// protocol handshake. It generates ephemeral and static key pairs for the responder and
+    /// prepares the handshake state. The authority keypair, certificate validity period, and
+    /// custom random number generator are also configured. The custom random number generator
+    /// is used to generate the ephemeral key pair for the handshake process. Returns an error if
+    /// the initialization fails.
+    #[inline]
     pub fn new_with_rng<R: rand::Rng + ?Sized>(
         a: Keypair,
         cert_validity: u32,
@@ -216,6 +227,17 @@ impl Responder {
     ) -> Result<Box<Self>, Error> {
         Self::from_authority_kp_with_rng(public, private, cert_validity, &mut rand::thread_rng())
     }
+
+    /// Creates a new [`Responder`] instance with the provided 32-byte authority key pair and a
+    /// custom random number generator.
+    ///
+    /// Constructs a new [`Responder`] with a given public and private key pair, which represents
+    /// the responder's authority credentials. It verifies that the provided public key matches the
+    /// corresponding private key, ensuring the authenticity of the authority key pair. The
+    /// certificate validity duration is also set here. The custom random number generator is used
+    /// to generate the ephemeral key pair for the handshake process. Fails if the key pair is
+    /// mismatched or if the initialization fails.
+    #[inline]
     pub fn from_authority_kp_with_rng<R: rand::Rng + ?Sized>(
         public: &[u8; 32],
         private: &[u8; 32],
@@ -264,6 +286,19 @@ impl Responder {
             &mut rand::thread_rng(),
         )
     }
+
+    /// Executes the first step of the Noise NX protocol handshake for the responder with
+    /// the current time and a custom RNG.
+    ///
+    /// This method handles the initial processing of the initiator's message by interpreting
+    /// the provided ephemeral public key, deriving shared secrets, and setting up the session
+    /// ciphers. It performs operations such as mixing the handshake hash, decrypting, and hashing
+    /// the ephemeral public key, and encrypting and hashing the static public key. Additionally,
+    /// it generates a signature noise message and encrypts it to be included in the response.
+    ///
+    /// The method finalizes by configuring the session ciphers for secure communication, returning
+    /// both the response message and a `NoiseCodec` instance for further message encryption and
+    /// decryption. On failure, it returns an error if decryption or encryption operations fail.
     #[inline]
     pub fn step_1_with_now_rng<R: rand::Rng + rand::CryptoRng>(
         &mut self,

protocols/v2/noise-sv2/src/signature_message.rs

@@ -79,6 +79,24 @@ impl SignatureNoiseMessage {
             .as_secs() as u32;
         self.verify_with_now(pk, authority_pk, now)
     }
+
+    /// Verifies the validity and authenticity of the `SignatureNoiseMessage` at a given timestamp.
+    ///
+    /// This method checks that the message is within its validity period defined by `valid_from`
+    /// and `not_valid_after`, and verifies the Schnorr signature using the provided public keys.
+    /// It computes the message hash using SHA-256 over the message components concatenated with
+    /// the public key serialization. If `authority_pk` is provided, the signature is verified
+    /// against it; otherwise, the message is assumed valid.
+    ///
+    /// # Parameters
+    /// - `pk`: A reference to the `XOnlyPublicKey` of the responder.
+    /// - `authority_pk`: An optional reference to the `XOnlyPublicKey` of the authority, used for
+    ///   signature verification.
+    /// - `now`: The current time as a Unix timestamp, used to check the validity period.
+    ///
+    /// # Returns
+    /// Returns `true` if the message is valid and the signature is successfully verified, `false`
+    /// otherwise.
     #[inline]
     pub fn verify_with_now(
         self,
@@ -115,6 +133,14 @@ impl SignatureNoiseMessage {
     pub fn sign(msg: &mut [u8; 74], static_pk: &XOnlyPublicKey, kp: &Keypair) {
         Self::sign_with_rng(msg, static_pk, kp, &mut rand::thread_rng());
     }
+
+    /// Creates a Schnorr signature for the message, combining the version, validity period, and
+    /// the static public key of the server (`static_pk`). The resulting signature is then written
+    /// into the provided message buffer (`msg`).
+    ///
+    /// This function takes a random number generator (`R`) to generate the random number used in
+    /// the signature generation.
+    #[inline]
     pub fn sign_with_rng<R: rand::Rng + rand::CryptoRng>(
         msg: &mut [u8; 74],
         static_pk: &XOnlyPublicKey,