From ede4b23e8a1c79d958777228b52e37ba2be9b0e5 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jon=20H=C3=A4ggblad?= Date: Wed, 18 Sep 2024 10:25:49 +0200 Subject: [PATCH] Fix clippy::too-long-first-doc-paragraph (#4897) --- common/bin-common/src/version_checker/mod.rs | 2 ++ common/dkg/src/bte/encryption.rs | 1 + common/dkg/src/dealing.rs | 2 ++ common/dkg/src/interpolation/mod.rs | 4 ++++ .../src/authentication/encrypted_address.rs | 2 ++ common/nym_offline_compact_ecash/src/scheme/mod.rs | 1 + common/nymcoconut/src/scheme/keygen.rs | 3 +++ common/nymsphinx/addressing/src/nodes.rs | 2 ++ common/nymsphinx/chunking/src/fragment.rs | 7 +++++++ common/nymsphinx/chunking/src/set.rs | 4 ++++ common/nymsphinx/src/preparer/mod.rs | 2 ++ common/socks5/proxy-helpers/src/connection_controller.rs | 9 ++++++--- nym-outfox/src/lion.rs | 7 ++++--- sdk/rust/nym-sdk/src/bandwidth/client.rs | 2 ++ sdk/rust/nym-sdk/src/mixnet/client.rs | 2 ++ 15 files changed, 44 insertions(+), 6 deletions(-) diff --git a/common/bin-common/src/version_checker/mod.rs b/common/bin-common/src/version_checker/mod.rs index a3968d610c..238a8ef85b 100644 --- a/common/bin-common/src/version_checker/mod.rs +++ b/common/bin-common/src/version_checker/mod.rs @@ -4,6 +4,8 @@ use semver::SemVerError; pub use semver::Version; +/// Checks if the version is minor version compatible. +/// /// Checks whether given `version` is compatible with a given semantic version requirement `req` /// according to major-minor semver rules. The semantic version requirement can be passed as a full, /// concrete version number, because that's what we'll have in our Cargo.toml files (e.g. 0.3.2). diff --git a/common/dkg/src/bte/encryption.rs b/common/dkg/src/bte/encryption.rs index aa2eef98ac..8cd6a3e774 100644 --- a/common/dkg/src/bte/encryption.rs +++ b/common/dkg/src/bte/encryption.rs @@ -166,6 +166,7 @@ impl Ciphertexts { #[derive(Zeroize)] #[zeroize(drop)] /// Randomness generated during ciphertext generation that is required for proofs of knowledge. +/// /// It must be handled with extreme care as its misuse might help malicious parties to recover /// the underlying plaintext. pub struct HazmatRandomness { diff --git a/common/dkg/src/dealing.rs b/common/dkg/src/dealing.rs index 6cc8afccb3..a051f9f88c 100644 --- a/common/dkg/src/dealing.rs +++ b/common/dkg/src/dealing.rs @@ -320,6 +320,8 @@ impl<'a> TryFrom<&'a nym_contracts_common::dealings::ContractSafeBytes> for Deal } } +/// Try to recover the verification keys from the provided dealings. +/// /// Attempt to run the `VkCombine` algorithm to obtain the public master verification key, `VK` /// alongside shares of the verification key, `shvk_{1}`, `shvk_{2}`, ... `svhk_{n}`, where n is the number of receivers. /// diff --git a/common/dkg/src/interpolation/mod.rs b/common/dkg/src/interpolation/mod.rs index 2862d84f8a..caedc1114e 100644 --- a/common/dkg/src/interpolation/mod.rs +++ b/common/dkg/src/interpolation/mod.rs @@ -64,6 +64,8 @@ fn generate_lagrangian_coefficients_at_x( Ok(res) } +/// Lagrange interpolation at x. +/// /// Performs a Lagrange interpolation at specified x for a polynomial defined by set of coordinates /// (x, f(x)), where x is a `Scalar` and f(x) is a generic type that can be obtained by evaluating `f` at `x`. /// It can be used for Scalars, G1 and G2 points. @@ -85,6 +87,8 @@ where .sum()) } +/// Lagrange interpolation at the origin. +/// /// Performs a Lagrange interpolation at the origin for a polynomial defined by set of coordinates /// (x, f(x)), where x is a `Scalar` and f(x) is a generic type that can be obtained by evaluating `f` at `x`. /// It can be used for Scalars, G1 and G2 points. diff --git a/common/gateway-requests/src/authentication/encrypted_address.rs b/common/gateway-requests/src/authentication/encrypted_address.rs index 2d94520ac1..bd500932c7 100644 --- a/common/gateway-requests/src/authentication/encrypted_address.rs +++ b/common/gateway-requests/src/authentication/encrypted_address.rs @@ -10,6 +10,8 @@ use thiserror::Error; pub const ENCRYPTED_ADDRESS_SIZE: usize = DESTINATION_ADDRESS_LENGTH; +/// Replacement for what used to be an `AuthToken`. +/// /// Replacement for what used to be an `AuthToken`. We used to be generating an `AuthToken` based on /// local secret and remote address in order to allow for authentication. Due to changes in registration /// and the fact we are deriving a shared key, we are encrypting remote's address with the previously diff --git a/common/nym_offline_compact_ecash/src/scheme/mod.rs b/common/nym_offline_compact_ecash/src/scheme/mod.rs index 050a9e7eb6..8912bf91eb 100644 --- a/common/nym_offline_compact_ecash/src/scheme/mod.rs +++ b/common/nym_offline_compact_ecash/src/scheme/mod.rs @@ -616,6 +616,7 @@ fn compute_kappa( } /// Represents the unique payment information associated with the payment. +/// /// The bytes representing the payment information encode the public key of the /// provider with whom you are spending the payment, timestamp and a unique random 32 bytes. /// diff --git a/common/nymcoconut/src/scheme/keygen.rs b/common/nymcoconut/src/scheme/keygen.rs index 90891acd94..85e057793d 100644 --- a/common/nymcoconut/src/scheme/keygen.rs +++ b/common/nymcoconut/src/scheme/keygen.rs @@ -581,6 +581,7 @@ impl TryFrom<&[u8]> for KeyPair { } /// Generate a single Coconut keypair ((x, y0, y1...), (g2^x, g2^y0, ...)). +/// /// It is not suitable for threshold credentials as all subsequent calls to `keygen` generate keys /// that are independent of each other. pub fn keygen(params: &Parameters) -> KeyPair { @@ -599,6 +600,8 @@ pub fn keygen(params: &Parameters) -> KeyPair { } } +/// Generate Coconut keypairs. +/// /// Generate a set of n Coconut keypairs [((x, y0, y1...), (g2^x, g2^y0, ...)), ...], /// such that they support threshold aggregation by `threshold` number of parties. /// It is expected that this procedure is executed by a Trusted Third Party. diff --git a/common/nymsphinx/addressing/src/nodes.rs b/common/nymsphinx/addressing/src/nodes.rs index 9569d4bbc8..e0cd745ae9 100644 --- a/common/nymsphinx/addressing/src/nodes.rs +++ b/common/nymsphinx/addressing/src/nodes.rs @@ -12,6 +12,8 @@ use thiserror::Error; pub type NodeIdentity = identity::PublicKey; pub const NODE_IDENTITY_SIZE: usize = identity::PUBLIC_KEY_LENGTH; +/// Encodoing and decoding node routing information. +/// /// This module is responsible for encoding and decoding node routing information, so that /// they could be later put into an appropriate field in a sphinx header. /// Currently, that routing information is an IP address, but in principle it can be anything diff --git a/common/nymsphinx/chunking/src/fragment.rs b/common/nymsphinx/chunking/src/fragment.rs index 504cfa9ba0..715a7ea400 100644 --- a/common/nymsphinx/chunking/src/fragment.rs +++ b/common/nymsphinx/chunking/src/fragment.rs @@ -22,6 +22,8 @@ use std::fmt::{self, Debug, Formatter}; // (the current limitation for making the seemingly trivial change is "linked id" which // has to have same amount of space available and right now it only has 31 bits available) +/// Length of the header of a `Fragment` when it's part of a single `FragmentSet`. +/// /// When the underlying message has to be split into multiple Fragments, but still manages to fit /// into a single `FragmentSet`, each `FragmentHeader` needs to hold additional information to allow /// for correct message reconstruction: 4 bytes for set id, 1 byte to represent total number @@ -29,6 +31,8 @@ use std::fmt::{self, Debug, Formatter}; /// and finally an extra byte to indicate the fragment has no links to other sets. pub const UNLINKED_FRAGMENTED_HEADER_LEN: usize = 7; +/// Length of the header of a `Fragment` when it's linked. +/// /// Logically almost identical to `UNLINKED_FRAGMENTED_HEADER_LEN`, however, the extra three /// bytes are due to changing the final byte that used to indicate the `Fragment` is not linked /// into 4 byte id of either previous or the next set. @@ -111,6 +115,7 @@ impl FragmentIdentifier { } /// The basic unit of division of underlying bytes message sent through the mix network. +/// /// Each `Fragment` after being marshaled is guaranteed to fit into a single sphinx packet. /// The `Fragment` itself consists of part, or whole of, message to be sent as well as additional /// header used to reconstruct the message after being received. @@ -283,6 +288,8 @@ impl Fragment { } } +/// Header of a `Fragment` that is used to be able to reconstruct the original message. +/// /// In order to be able to re-assemble fragmented message sent through a mix-network, some /// metadata is attached alongside the actual message payload. The idea is to include as little /// of that data as possible due to computationally very costly process of sphinx encapsulation. diff --git a/common/nymsphinx/chunking/src/set.rs b/common/nymsphinx/chunking/src/set.rs index 6aa492af46..a694f608d6 100644 --- a/common/nymsphinx/chunking/src/set.rs +++ b/common/nymsphinx/chunking/src/set.rs @@ -14,6 +14,8 @@ pub const fn max_unlinked_set_payload_length(max_plaintext_size: usize) -> usize u8::MAX as usize * unlinked_fragment_payload_max_len(max_plaintext_size) } +/// Maximum payload length for a set that is being linked to another one, but is not the last one. +/// /// If the set is being linked to another one, by either being the very first set, or the very last, /// one of its `Fragment`s must be changed from "unlinked" into "linked" to compensate for a tiny /// bit extra data overhead: id of the other set. @@ -25,6 +27,8 @@ pub const fn max_one_way_linked_set_payload_length(max_plaintext_size: usize) -> - (LINKED_FRAGMENTED_HEADER_LEN - UNLINKED_FRAGMENTED_HEADER_LEN) } +/// Set payload length for a set that is being linked to another one, but is not the last one. +/// /// If the set is being linked two others sets by being stuck in the middle of divided message, /// two of its `Fragment`s (first and final one) must be changed from /// "unlinked" into "linked" to compensate for data overhead. diff --git a/common/nymsphinx/src/preparer/mod.rs b/common/nymsphinx/src/preparer/mod.rs index 7cdddd53a1..f7d5e0d256 100644 --- a/common/nymsphinx/src/preparer/mod.rs +++ b/common/nymsphinx/src/preparer/mod.rs @@ -302,6 +302,8 @@ pub trait FragmentPreparer { } } +/// Prepares the message that is to be sent through the mix network. +/// /// Prepares the message that is to be sent through the mix network by attaching /// an optional reply-SURB, padding it to appropriate length, encrypting its content, /// and chunking into appropriate size [`Fragment`]s. diff --git a/common/socks5/proxy-helpers/src/connection_controller.rs b/common/socks5/proxy-helpers/src/connection_controller.rs index be143552d7..5c2e2f22c1 100644 --- a/common/socks5/proxy-helpers/src/connection_controller.rs +++ b/common/socks5/proxy-helpers/src/connection_controller.rs @@ -10,9 +10,11 @@ use nym_task::connections::{ConnectionCommand, ConnectionCommandSender}; use nym_task::TaskClient; use std::collections::{HashMap, HashSet}; -/// A generic message produced after reading from a socket/connection. It includes data that was -/// actually read alongside boolean indicating whether the connection got closed so that -/// remote could act accordingly. +/// A generic message produced after reading from a socket/connection. +/// +/// A generic message produced after reading from a socket/connection that includes data that was +/// actually read alongside boolean indicating whether the connection got closed so that remote +/// could act accordingly. #[derive(Debug)] pub struct ConnectionMessage { pub payload: Vec, @@ -20,6 +22,7 @@ pub struct ConnectionMessage { } /// Channel responsible for sending data that was received from mix network into particular connection. +/// /// Data includes the actual payload that is to be written onto the connection /// alongside boolean indicating whether the remote connection was closed after producing this message, /// so that the local connection should also shut down. diff --git a/nym-outfox/src/lion.rs b/nym-outfox/src/lion.rs index 05aaf8d361..3e05c3613a 100644 --- a/nym-outfox/src/lion.rs +++ b/nym-outfox/src/lion.rs @@ -55,9 +55,10 @@ pub fn lion_transform_decrypt(message: &mut [u8], key: &[u8]) -> Result<(), Outf lion_transform(message, key, [3, 2, 1]) } -/// The core of the lion transform function, that takes a message and a key, -/// and applies the all-or-nothing transform. The key schedule represents the -/// values of the 3 subkeys used by the 3 phases of the transform. +/// The core of the lion transform function. +/// +/// Takes a message and a key, and applies the all-or-nothing transform. The key schedule +/// represents the values of the 3 subkeys used by the 3 phases of the transform. /// /// The `key` must be 32 bytes, and the `message` >= 48. /// diff --git a/sdk/rust/nym-sdk/src/bandwidth/client.rs b/sdk/rust/nym-sdk/src/bandwidth/client.rs index 3f5acbd5e9..68a4edb347 100644 --- a/sdk/rust/nym-sdk/src/bandwidth/client.rs +++ b/sdk/rust/nym-sdk/src/bandwidth/client.rs @@ -10,6 +10,8 @@ use nym_validator_client::{nyxd, DirectSigningHttpRpcNyxdClient}; use std::ops::Deref; use zeroize::Zeroizing; +/// Represents a client that can be used to acquire bandwidth. +/// /// Represents a client that can be used to acquire bandwidth. You typically create one when you /// want to connect to the mixnet using paid coconut bandwidth credentials. /// The way to create this client is by calling diff --git a/sdk/rust/nym-sdk/src/mixnet/client.rs b/sdk/rust/nym-sdk/src/mixnet/client.rs index 558109f4de..14138b0baf 100644 --- a/sdk/rust/nym-sdk/src/mixnet/client.rs +++ b/sdk/rust/nym-sdk/src/mixnet/client.rs @@ -265,6 +265,8 @@ where } } +/// Represents a client that is not yet connected to the mixnet. +/// /// Represents a client that is not yet connected to the mixnet. You typically create one when you /// want to have a separate configuration and connection phase. Once the mixnet client builder is /// configured, call [`MixnetClientBuilder::connect_to_mixnet()`] or