refactor rust-docs on new functions

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

@@ -176,11 +176,11 @@ impl Initiator {
     /// 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.
+    /// See [`Self::new`] for more details.
     ///
-    /// The custom random number generator is used to generate the ephemeral key pair.
+    /// The custom random number generator is used to generate the ephemeral key pair. It should be
+    /// provided in order to not implicitely rely on `std` and allow `no_std` environments to
+    /// provide a hardware random number generator for example.
     #[inline]
     pub fn new_with_rng<R: rand::Rng + ?Sized>(
         pk: Option<XOnlyPublicKey>,
@@ -216,13 +216,11 @@ impl Initiator {
     /// 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.
+    /// See [`Self::from_raw_k`] for more details.
     ///
-    /// Typically used when the initiator is aware of the responder's public key in advance and
-    /// wants to use a custom random number generator.
+    /// The custom random number generator should be provided in order to not implicitely rely on
+    /// `std` and allow `no_std` environments to provide a hardware random number generator for
+    /// example.
     #[inline]
     pub fn from_raw_k_with_rng<R: rand::Rng + ?Sized>(
         key: [u8; 32],
@@ -246,12 +244,11 @@ impl Initiator {
     /// 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.
+    /// See [`Self::without_pk`] for more details.
+    ///
+    /// The custom random number generator should be provided in order to not implicitely rely on
+    /// `std` and allow `no_std` environments to provide a hardware random number generator for
+    /// example.
     #[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))
@@ -307,6 +304,14 @@ impl Initiator {
             .as_secs() as u32;
         self.step_2_with_now(message, now)
     }
+
+    /// Processes the second step of the Noise NX protocol handshake for the initiator given the
+    /// current system time.
+    ///
+    /// See [`Self::step_2`] for more details.
+    ///
+    /// The current system time should be provided to avoid relying on `std` and allow `no_std`
+    /// environments to use another source of time.
     pub fn step_2_with_now(
         &mut self,
         message: [u8; INITIATOR_EXPECTED_HANDSHAKE_MESSAGE_SIZE],

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

@@ -184,12 +184,11 @@ impl Responder {
     /// 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.
+    /// See [`Self::new`] for more details.
+    ///
+    /// The custom random number generator should be provided in order to not implicitely rely on
+    /// `std` and allow `no_std` environments to provide a hardware random number generator for
+    /// example.
     #[inline]
     pub fn new_with_rng<R: rand::Rng + ?Sized>(
         a: Keypair,
@@ -231,12 +230,11 @@ impl Responder {
     /// 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.
+    /// See [`Self::from_authority_kp`] for more details.
+    ///
+    /// The custom random number generator should be provided in order to not implicitely rely on
+    /// `std` and allow `no_std` environments to provide a hardware random number generator for
+    /// example.
     #[inline]
     pub fn from_authority_kp_with_rng<R: rand::Rng + ?Sized>(
         public: &[u8; 32],
@@ -287,18 +285,14 @@ impl Responder {
         )
     }
 
-    /// Executes the first step of the Noise NX protocol handshake for the responder with
-    /// the current time and a custom RNG.
+    /// Executes the first step of the Noise NX protocol handshake for the responder given
+    /// the current time and a custom random number generator.
     ///
-    /// 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.
+    /// See [`Self::step_1`] for more details.
     ///
-    /// 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.
+    /// The current time and the custom random number generatorshould be provided in order to not
+    /// implicitely rely on `std` and allow `no_std` environments to provide a hardware random
+    /// number generator for example.
     #[inline]
     pub fn step_1_with_now_rng<R: rand::Rng + rand::CryptoRng>(
         &mut self,

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

@@ -82,21 +82,11 @@ impl SignatureNoiseMessage {
 
     /// 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.
+    /// See [`Self::verify`] for more details.
     ///
-    /// # 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.
+    /// The current system time should be provided to avoid relying on `std` and allow `no_std`
+    /// environments to use another source of time.
+
     #[inline]
     pub fn verify_with_now(
         self,
@@ -134,12 +124,14 @@ impl SignatureNoiseMessage {
         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`).
+    /// Signs a [`SignatureNoiseMessage`] using the provided keypair (`kp`) and a custom random
+    /// number generator.
+    ///
+    /// See [`Self::sign`] for more details.
     ///
-    /// This function takes a random number generator (`R`) to generate the random number used in
-    /// the signature generation.
+    /// The random number generator is used in the signature generation. It should be provided in
+    /// order to not implicitely rely on `std` and allow `no_std` environments to provide a
+    /// hardware random number generator for example.
     #[inline]
     pub fn sign_with_rng<R: rand::Rng + rand::CryptoRng>(
         msg: &mut [u8; 74],