Merge pull request #2905 from AleoHQ/fix/doc-and-improve

Fix and improve some documentation.

cli/src/commands/developer/mod.rs

@@ -100,7 +100,7 @@ impl Developer {
         Ok(package)
     }
 
-    /// Parses the record string. If the string is a plaintext, then attempt to decrypt it.
+    /// Parses the record string. If the string is a ciphertext, then attempt to decrypt it.
     fn parse_record(
         private_key: &PrivateKey<CurrentNetwork>,
         record: &str,

cli/src/helpers/updater.rs

@@ -59,7 +59,7 @@ impl Updater {
         Ok(status)
     }
 
-    /// Check if there is an available update for `aleo` and return the newest release.
+    /// Check if there is an available update for `snarkos` and return the newest release.
     pub fn update_available() -> Result<String, UpdaterError> {
         let updater = github::Update::configure()
             .repo_owner(Self::SNARKOS_REPO_OWNER)

node/bft/src/gateway.rs

@@ -215,7 +215,7 @@ impl<N: Network> Gateway<N> {
         2 * MAX_GC_ROUNDS as usize * self.max_committee_size()
     }
 
-    /// Thne maximum number of transmission requests to cache.
+    /// The maximum number of transmission requests to cache.
     fn max_cache_transmissions(&self) -> usize {
         self.max_cache_certificates() * MAX_TRANSMISSIONS_PER_BATCH
     }

node/sync/locators/src/block_locators.rs

@@ -35,7 +35,7 @@ pub struct BlockLocators<N: Network> {
 }
 
 impl<N: Network> BlockLocators<N> {
-    /// Initializes a new instance of the block locators.
+    /// Initializes a new instance of the block locators, checking the validity of the block locators.
     pub fn new(recents: IndexMap<u32, N::BlockHash>, checkpoints: IndexMap<u32, N::BlockHash>) -> Result<Self> {
         // Construct the block locators.
         let locators = Self { recents, checkpoints };
@@ -45,7 +45,7 @@ impl<N: Network> BlockLocators<N> {
         Ok(locators)
     }
 
-    /// Initializes a new instance of the block locators.
+    /// Initializes a new instance of the block locators, without checking the validity of the block locators.
     pub fn new_unchecked(recents: IndexMap<u32, N::BlockHash>, checkpoints: IndexMap<u32, N::BlockHash>) -> Self {
         Self { recents, checkpoints }
     }
@@ -149,13 +149,13 @@ impl<N: Network> BlockLocators<N> {
         // Ensure the block checkpoints are well-formed.
         let last_checkpoint_height = Self::check_block_checkpoints(checkpoints)?;
 
-        // Ensure the `last_recent_height` is at or above `last_checkpoint_height - NUM_RECENTS`.
+        // Ensure the `last_recent_height` is at or above `last_checkpoint_height - NUM_RECENT_BLOCKS`.
         let threshold = last_checkpoint_height.saturating_sub(NUM_RECENT_BLOCKS as u32);
         if last_recent_height < threshold {
             bail!("Recent height ({last_recent_height}) cannot be below checkpoint threshold ({threshold})")
         }
 
-        // If the `last_recent_height` is below NUM_RECENTS, ensure the genesis hash matches in both maps.
+        // If the `last_recent_height` is below NUM_RECENT_BLOCKS, ensure the genesis hash matches in both maps.
         if last_recent_height < NUM_RECENT_BLOCKS as u32
             && recents.get(&0).copied().unwrap_or_default() != checkpoints.get(&0).copied().unwrap_or_default()
         {
@@ -186,7 +186,7 @@ impl<N: Network> BlockLocators<N> {
         if recents.is_empty() {
             bail!("There must be at least 1 recent block")
         }
-        // Ensure the number of recent blocks is at most NUM_RECENTS.
+        // Ensure the number of recent blocks is at most NUM_RECENT_BLOCKS.
         // This redundant check ensures we early exit if the number of recent blocks is too large.
         if recents.len() > NUM_RECENT_BLOCKS {
             bail!("There can be at most {NUM_RECENT_BLOCKS} blocks in the map")
@@ -211,7 +211,7 @@ impl<N: Network> BlockLocators<N> {
         if last_height < NUM_RECENT_BLOCKS as u32 && recents.len().saturating_sub(1) as u32 != last_height {
             bail!("As the last height is below {NUM_RECENT_BLOCKS}, the number of recent blocks must match the height")
         }
-        // Otherwise, ensure the number of recent blocks matches NUM_RECENTS.
+        // Otherwise, ensure the number of recent blocks matches NUM_RECENT_BLOCKS.
         if last_height >= NUM_RECENT_BLOCKS as u32 && recents.len() != NUM_RECENT_BLOCKS {
             bail!("Number of recent blocks must match {NUM_RECENT_BLOCKS}")
         }

node/sync/src/block_sync.rs

@@ -58,7 +58,7 @@ pub enum BlockSyncMode {
 }
 
 impl BlockSyncMode {
-    /// Returns `true` if the node is in router moder.
+    /// Returns `true` if the node is in router mode.
     pub const fn is_router(&self) -> bool {
         matches!(self, Self::Router)
     }
@@ -75,7 +75,7 @@ impl BlockSyncMode {
 /// - When a request is inserted, the `requests` map and `request_timestamps` map insert an entry for the request height.
 /// - When a response is inserted, the `requests` map inserts the entry for the request height.
 /// - When a request is completed, the `requests` map still has the entry, but its `sync_ips` is empty;
-/// - the `request_timestamps` map remains unchanged.
+///   the `request_timestamps` map remains unchanged.
 /// - When a response is removed/completed, the `requests` map and `request_timestamps` map also remove the entry for the request height.
 /// - When a request is timed out, the `requests`, `request_timestamps`, and `responses` map remove the entry for the request height;
 #[derive(Clone, Debug)]

node/tcp/src/helpers/config.rs

@@ -26,7 +26,9 @@ pub struct Config {
     /// A user-friendly identifier of the Tcp. It is visible in the logs, where it allows Tcp instances to be
     /// distinguished more easily if multiple are run at the same time.
     ///
-    /// note: If set to `None`, Tcp will automatically be assigned a sequential, zero-based numeric identifier.
+    /// note: If set to `None` when the configuration is initially created, it will be automatically assigned
+    /// (the string representation of) a sequential, zero-based numeric identifier. So this is essentially never
+    /// `None`, in a running node.
     pub name: Option<String>,
     /// The IP address the Tcp's connection listener should bind to.
     ///

node/tcp/src/helpers/known_peers.rs

@@ -33,7 +33,7 @@ impl KnownPeers {
         self.0.read().get(&addr).map(Arc::clone)
     }
 
-    /// Removes an address to the list of known peers.
+    /// Removes an address from the list of known peers.
     pub fn remove(&self, addr: SocketAddr) -> Option<Arc<Stats>> {
         self.0.write().remove(&addr)
     }

node/tcp/src/protocols/on_connect.rs

@@ -12,10 +12,6 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
-//! Opt-in protocols available to the node; each protocol is expected to spawn its own task that runs throughout the
-//! node's lifetime and handles a specific functionality. The communication with these tasks is done via dedicated
-//! handler objects.
-
 use std::net::SocketAddr;
 
 use tokio::sync::{mpsc, oneshot};

node/tcp/src/tcp.rs

@@ -69,7 +69,7 @@ pub struct InnerTcp {
     listening_addr: OnceCell<SocketAddr>,
     /// Contains objects used by the protocols implemented by the node.
     pub(crate) protocols: Protocols,
-    /// A list of connections that have not been finalized yet.
+    /// A set of connections that have not been finalized yet.
     connecting: Mutex<HashSet<SocketAddr>>,
     /// Contains objects related to the node's active connections.
     connections: Connections,