chore: fix stale doc comments

clarity/src/vm/contexts.rs

@@ -1257,7 +1257,7 @@ impl<'a, 'b, 'hooks> ExecutionState<'a, 'b, 'hooks> {
     /// `allow_private` should always be set to `false` for user transactions:
     ///  this ensures that only `define-public` and `define-read-only` methods can
     ///  be invoked. The `allow_private` mode should only be used by
-    ///  `Environment::execute_contract_allow_private`.
+    ///  `ExecutionState::execute_contract_allow_private`.
     fn inner_execute_contract(
         &mut self,
         invoke_ctx: &InvocationContext,

clarity/src/vm/database/clarity_db.rs

@@ -501,7 +501,7 @@ impl<'a> ClarityDatabase<'a> {
         self.store.put_data(key, &value.serialize())
     }
 
-    /// Like `put()`, but returns the serialized byte size of the stored value
+    /// Like `put_data()`, but returns the serialized byte size of the stored value
     pub fn put_data_with_size<T: ClaritySerializable>(
         &mut self,
         key: &str,
@@ -1102,10 +1102,14 @@ impl ClarityDatabase<'_> {
     }
 
     /// Get the last-known burnchain block height.
-    /// Note that this is _not_ the burnchain height in which this block was mined!
-    /// This is the burnchain block height of the parent of the Stacks block at the current Stacks
-    /// block height (i.e. that returned by `get_index_block_header_hash` for
-    /// `get_current_block_height`).
+    ///
+    /// Behavior depends on the active Clarity epoch:
+    /// * Before epoch 3.0, this is the burnchain block height of the parent of the Stacks block
+    ///   at the current Stacks block height (i.e. that returned by `get_index_block_header_hash`
+    ///   for `get_current_block_height`) — note this is _not_ the burnchain height in which this
+    ///   block was mined.
+    /// * In epoch 3.0+, this is the current burnchain tip height (queried directly via
+    ///   `BurnStateDB::get_tip_burn_block_height`).
     pub fn get_current_burnchain_block_height(&mut self) -> Result<u32, VmExecutionError> {
         let cur_stacks_height = self.store.get_current_block_height();
 

clarity/src/vm/database/structures.rs

@@ -544,7 +544,7 @@ impl<'db, 'conn> STXBalanceSnapshot<'db, 'conn> {
     }
 
     /// Increase the account's current lock to `new_total_locked`.
-    /// Panics if `self` was not locked by V2 PoX.
+    /// Returns Err(VmInternalError::Expect) if `self` was not locked by V2 PoX.
     pub fn increase_lock_v2(&mut self, new_total_locked: u128) -> Result<(), VmExecutionError> {
         let unlocked = self.unlock_available_tokens_if_any()?;
         if unlocked > 0 {
@@ -763,7 +763,7 @@ impl<'db, 'conn> STXBalanceSnapshot<'db, 'conn> {
     }
 
     /// Increase the account's current lock to `new_total_locked`.
-    /// Panics if `self` was not locked by V3 PoX.
+    /// Returns Err(VmInternalError::Expect) if `self` was not locked by V3 PoX.
     pub fn increase_lock_v3(&mut self, new_total_locked: u128) -> Result<(), VmExecutionError> {
         let unlocked = self.unlock_available_tokens_if_any()?;
         if unlocked > 0 {
@@ -863,7 +863,7 @@ impl<'db, 'conn> STXBalanceSnapshot<'db, 'conn> {
 
     /// Extend this account's current lock to `unlock_burn_height`.
     /// After calling, this method will set the balance to a "LockedPoxFour" balance,
-    ///  because this method is only invoked as a result of PoX3 interactions
+    ///  because this method is only invoked as a result of PoX4 interactions
     pub fn extend_lock_v4(&mut self, unlock_burn_height: u64) -> Result<(), VmExecutionError> {
         let unlocked = self.unlock_available_tokens_if_any()?;
         if unlocked > 0 {
@@ -889,7 +889,7 @@ impl<'db, 'conn> STXBalanceSnapshot<'db, 'conn> {
     }
 
     /// Increase the account's current lock to `new_total_locked`.
-    /// Panics if `self` was not locked by V3 PoX.
+    /// Panics if `self` was not locked by V4 PoX.
     pub fn increase_lock_v4(&mut self, new_total_locked: u128) -> Result<(), VmExecutionError> {
         let unlocked = self.unlock_available_tokens_if_any()?;
         if unlocked > 0 {
@@ -929,7 +929,7 @@ impl<'db, 'conn> STXBalanceSnapshot<'db, 'conn> {
     }
 
     /// Return true iff `self` represents a snapshot that has a lock
-    ///  created by PoX v3.
+    ///  created by PoX v4.
     pub fn is_v4_locked(&mut self) -> Result<bool, VmExecutionError> {
         match self.canonical_balance_repr()? {
             STXBalance::LockedPoxFour { .. } => Ok(true),
@@ -1036,7 +1036,8 @@ impl STXBalance {
     }
 
     /// This method returns the datastructure's lazy view of the unlock_height
-    ///  *while* factoring in the PoX 2 early unlock for PoX 1 and PoX 3 early unlock for PoX 2.
+    ///  *while* factoring in the PoX 2 early unlock for PoX 1, the PoX 3 early
+    ///  unlock for PoX 2, and the PoX 4 early unlock for PoX 3.
     /// This value is still lazy: this unlock height may be less than the current
     ///  burn block height, if so it will be updated in a canonicalized view.
     pub fn effective_unlock_height(
@@ -1159,9 +1160,9 @@ impl STXBalance {
     }
 
     /// Returns a canonicalized STXBalance at a given burn_block_height
-    /// (i.e., if burn_block_height >= unlock_height, then return struct where
-    ///   amount_unlocked = 0, unlock_height = 0), and the amount of tokens which
-    ///   are "unlocked" by the canonicalization
+    /// (i.e., if burn_block_height >= unlock_height, then return
+    ///   STXBalance::Unlocked { amount: total_balance }), and the amount of
+    ///   tokens which are "unlocked" by the canonicalization.
     pub fn canonical_repr_at_block(
         &self,
         burn_block_height: u64,

clarity/src/vm/errors.rs

@@ -173,8 +173,8 @@ pub enum RuntimeError {
 /// These errors halt evaluation and fail the transaction.
 pub enum EarlyReturnError {
     /// Failed to unwrap an `Optional` (`none`) or `Response` (`err` or `ok`) Clarity value.
-    /// The `Box<Value>` holds the original or thrown value. Triggered by `try!`, `unwrap-or`, or
-    /// `unwrap-err-or`.
+    /// The `Box<Value>` holds the original or thrown value. Triggered by `try!`, `unwrap!`, or
+    /// `unwrap-err!`.
     UnwrapFailed(Box<Value>),
     /// An 'asserts!' expression evaluated to false.
     /// The `Box<Value>` holds the value provided as the second argument to `asserts!`.

clarity/src/vm/functions/database.rs

@@ -934,7 +934,7 @@ pub fn special_delete_entry_v205(
 /// # Errors:
 /// - [`RuntimeCheckErrorKind`] cost errors (e.g., `CostOverflow`, `CostBalanceExceeded`) from [`runtime_cost`].
 /// - [`RuntimeCheckErrorKind::IncorrectArgumentCount`] if there aren't 2 arguments.
-/// - [`RuntimeCheckErrorKind::GetBlockInfoExpectPropertyName`] if `args[0]` isn't a ClarityName or isn't a valid [`BlockInfoProperty`].
+/// - [`RuntimeCheckErrorKind::Unreachable`] if `args[0]` isn't a ClarityName or isn't a valid [`BlockInfoProperty`] (the static analyzer normally rejects this with [`StaticCheckErrorKind::GetBlockInfoExpectPropertyName`] before reaching runtime).
 /// - [`RuntimeCheckErrorKind::TypeValueError`] if `args[1]` doesn't evaluate to a `uint`.
 /// - [`VmExecutionError`] propagated from [`eval`] when evaluating `args[1]`.
 /// - [`VmInternalError`] from database operations when retrieving block information.
@@ -1091,15 +1091,15 @@ pub fn special_get_block_info(
 }
 
 /// Handles the `get-burn-block-info?` special function.
-/// Interprets `args` as variables `[property_name, burn_block_height]`, and returns
-/// a property value determined by `property_name`:
-/// - `header_hash` returns the burn block header hash at `burn_block_height`
-/// - `pox_addrs` returns the list of PoX addresses paid out at `burn_block_height`
+/// Interprets `args` as variables `[property-name, burn-block-height]`, and returns
+/// a property value determined by `property-name`:
+/// - `header-hash` returns the burn block header hash at `burn-block-height`
+/// - `pox-addrs` returns the list of PoX addresses paid out at `burn-block-height`
 ///
 /// # Errors:
 /// - [`RuntimeCheckErrorKind::IncorrectArgumentCount`] if there aren't 2 arguments.
-/// - [`RuntimeCheckErrorKind::GetBlockInfoExpectPropertyName`] if `args[0]` isn't a ClarityName.
-/// - [`RuntimeCheckErrorKind::NoSuchBurnBlockInfoProperty`] if `args[0]` isn't a [`BurnBlockInfoProperty`].
+/// - [`RuntimeCheckErrorKind::Unreachable`] if `args[0]` isn't a ClarityName (the static analyzer normally rejects this).
+/// - [`RuntimeCheckErrorKind::Unreachable`] if `args[0]` isn't a [`BurnBlockInfoProperty`] (the static analyzer normally rejects this with [`StaticCheckErrorKind::NoSuchBurnBlockInfoProperty`]).
 /// - [`RuntimeCheckErrorKind::TypeValueError`] if `args[1]` doesn't evaluate to a `uint`.
 /// - [`RuntimeCheckErrorKind`] cost errors (e.g., `CostOverflow`, `CostBalanceExceeded`) from [`runtime_cost`].
 /// - [`VmExecutionError`] propagated from [`eval`] when evaluating `args[1]`.
@@ -1302,7 +1302,7 @@ pub fn special_get_stacks_block_info(
 ///
 /// # Errors:
 /// - [`RuntimeCheckErrorKind::IncorrectArgumentCount`] if there aren't 2 arguments.
-/// - [`RuntimeCheckErrorKind::GetTenureInfoExpectPropertyName`] if `args[0]` isn't a ClarityName or isn't a valid [`TenureInfoProperty`].
+/// - [`RuntimeCheckErrorKind::Unreachable`] if `args[0]` isn't a ClarityName or isn't a valid [`TenureInfoProperty`] (the static analyzer normally rejects this with [`StaticCheckErrorKind::GetTenureInfoExpectPropertyName`] before reaching runtime).
 /// - [`RuntimeCheckErrorKind::TypeValueError`] if `args[1]` doesn't evaluate to a `uint`.
 /// - [`RuntimeCheckErrorKind`] cost errors (e.g., `CostOverflow`, `CostBalanceExceeded`) from [`runtime_cost`].
 /// - [`VmExecutionError`] propagated from [`eval`] when evaluating `args[1]`.

libsigner/src/events.rs

@@ -111,7 +111,7 @@ pub struct BlockProposalData {
 }
 
 impl BlockProposalData {
-    /// Create a new BlockProposalData for the provided server version and unknown bytes
+    /// Create a new BlockProposalData for the provided server version and miner diagnostic data.
     pub fn new(server_version: String, miner_diagnostic_data: MinerDiagnosticData) -> Self {
         Self {
             version: BLOCK_PROPOSAL_DATA_VERSION,
@@ -400,7 +400,7 @@ impl<T: SignerEventTrait> EventReceiver<T> for SignerEventReceiver<T> {
 
     /// Start listening on the given socket address.
     /// Returns the address that was bound.
-    /// Errors out if bind(2) fails
+    /// Panics if `HttpServer::http()` fails to bind to the listener address.
     fn bind(&mut self, listener: SocketAddr) -> Result<SocketAddr, EventError> {
         self.http_server = Some(HttpServer::http(listener).expect("failed to start HttpServer"));
         self.local_addr = Some(listener);

libsigner/src/http.rs

@@ -58,7 +58,7 @@ impl SignerHttpRequest {
 }
 
 /// Decode the HTTP request payload into its headers and body.
-/// Returns (verb, path, table of headers, body_offset) on success
+/// Returns a `SignerHttpRequest` (verb, path, table of headers, body_offset) on success.
 pub fn decode_http_request(payload: &[u8]) -> Result<SignerHttpRequest, EventError> {
     // realistically, there won't be more than 32 headers
     let mut headers_buf = [httparse::EMPTY_HEADER; MAX_HTTP_HEADERS];
@@ -123,7 +123,7 @@ pub fn decode_http_request(payload: &[u8]) -> Result<SignerHttpRequest, EventErr
 }
 
 /// Decode the HTTP response payload into its headers and body.
-/// Return the offset into payload where the body starts, and a table of headers.
+/// Return the table of headers and the offset into payload where the body starts.
 ///
 /// If the payload contains a status code other than 200, then RPCERror::HttpError(..) will be
 /// returned with the status code.

libsigner/src/runloop.rs

@@ -52,7 +52,7 @@ pub trait SignerRunLoop<R: Send, T: SignerEventTrait> {
     /// This is the main loop body for the signer. It continuously receives events from
     /// `event_recv`, polling for up to `self.get_event_timeout()` units of time.  Once it has
     /// polled for events, they are fed into `run_one_pass()`.  This continues until either
-    /// `run_one_pass()` returns `false`, or the event receiver hangs up.  At this point, this
+    /// `run_one_pass()` returns `Some(R)`, or the event receiver hangs up.  At this point, this
     /// method calls the `event_stop_signaler.send()` to terminate the receiver.
     ///
     /// This would run in a separate thread from the event receiver.

libsigner/src/signer_set.rs

@@ -48,7 +48,7 @@ pub enum Error {
 }
 
 impl SignerEntries {
-    /// Try to parse the reward set defined by `NakamotoSignEntry` into the SignerEntries struct
+    /// Try to parse the reward set defined by `NakamotoSignerEntry` into the SignerEntries struct
     pub fn parse(is_mainnet: bool, reward_set: &[NakamotoSignerEntry]) -> Result<Self, Error> {
         let mut signer_pk_to_id = HashMap::with_capacity(reward_set.len());
         let mut signer_id_to_pk = HashMap::with_capacity(reward_set.len());

libsigner/src/v0/messages.rs

@@ -354,7 +354,7 @@ pub struct MockProposal {
 }
 
 impl MockProposal {
-    /// Create a new mock proposal data struct from the provided peer info, chain id, and private key.
+    /// Create a new mock proposal data struct from the provided peer info and private key.
     pub fn new(peer_info: PeerInfo, stacks_private_key: &StacksPrivateKey) -> Self {
         let mut sig = Self {
             signature: MessageSignature::empty(),
@@ -1412,7 +1412,7 @@ impl BlockResponse {
         }
     }
 
-    /// Get the block accept data from the block response
+    /// Get the block rejection data from the block response
     pub fn as_block_rejection(&self) -> Option<&BlockRejection> {
         match self {
             BlockResponse::Rejected(rejection) => Some(rejection),
@@ -1530,7 +1530,8 @@ pub struct BlockResponseData {
 }
 
 impl BlockResponseData {
-    /// Create a new BlockResponseData for the provided tenure extend timestamp and unknown bytes
+    /// Create a new BlockResponseData from the provided tenure-extend timestamp, reject reason,
+    /// tenure-extend read-count timestamp, and failed-tx id. `unknown_bytes` is initialised empty.
     pub fn new(
         tenure_extend_timestamp: u64,
         reject_reason: RejectReason,
@@ -1625,7 +1626,7 @@ impl StacksMessageCodec for BlockResponseData {
     }
 }
 
-/// A rejection response from a signer for a proposed block
+/// An acceptance response from a signer for a proposed block
 #[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
 pub struct BlockAccepted {
     /// The signer signature hash of the block that was accepted

pox-locking/src/lib.rs

@@ -20,7 +20,7 @@
 //! This library provides a contract-call special case handler
 //! `crate::handle_contract_call_special_cases()` which matches a
 //! contract-call result against zero-address published contracts
-//! `pox`, `pox-2`, and `pox-3`. For each of those contracts, it
+//! `pox`, `pox-2`, `pox-3`, and `pox-4`. For each of those contracts, it
 //! checks if the function called requires applying or updating the
 //! `STXBalance` struct's locks, and if the function was successfully
 //! invoked. If so, it updates the PoX lock.

pox-locking/src/pox_2.rs

@@ -56,7 +56,7 @@ pub fn is_read_only(func_name: &str) -> bool {
 }
 
 /// Parse the returned value from PoX `stack-stx` and `delegate-stack-stx` functions
-///  from pox-2.clar or pox-3.clar into a format more readily digestible in rust.
+///  from pox-2.clar, pox-3.clar, or pox-4.clar into a format more readily digestible in rust.
 /// Panics if the supplied value doesn't match the expected tuple structure
 pub fn parse_pox_stacking_result(
     result: &Value,
@@ -98,7 +98,7 @@ pub fn parse_pox_stacking_result(
     }
 }
 
-/// Parse the returned value from PoX2 or PoX3 `stack-extend` and `delegate-stack-extend` functions
+/// Parse the returned value from PoX2, PoX3, or PoX4 `stack-extend` and `delegate-stack-extend` functions
 ///  into a format more readily digestible in rust.
 /// Panics if the supplied value doesn't match the expected tuple structure
 pub fn parse_pox_extend_result(result: &Value) -> std::result::Result<(PrincipalData, u64), i128> {
@@ -133,7 +133,7 @@ pub fn parse_pox_extend_result(result: &Value) -> std::result::Result<(Principal
     }
 }
 
-/// Parse the returned value from PoX2 or PoX3 `stack-increase` function
+/// Parse the returned value from PoX2, PoX3, or PoX4 `stack-increase` function
 ///  into a format more readily digestible in rust.
 /// Panics if the supplied value doesn't match the expected tuple structure
 pub fn parse_pox_increase(result: &Value) -> std::result::Result<(PrincipalData, u128), i128> {
@@ -172,7 +172,7 @@ pub fn parse_pox_increase(result: &Value) -> std::result::Result<(PrincipalData,
 /// Returns Ok( account snapshot ) when successful
 ///
 /// # Errors
-/// - Returns Error::PoxExtendNotLocked if this function was called on an account
+/// - Returns LockingError::PoxExtendNotLocked if this function was called on an account
 ///   which isn't locked. This *should* have been checked by the PoX v2 contract,
 ///   so this should surface in a panic.
 pub fn pox_lock_increase_v2(
@@ -225,7 +225,7 @@ pub fn pox_lock_increase_v2(
 /// Returns Ok(lock_amount) when successful
 ///
 /// # Errors
-/// - Returns Error::PoxExtendNotLocked if this function was called on an account
+/// - Returns LockingError::PoxExtendNotLocked if this function was called on an account
 ///   which isn't locked. This *should* have been checked by the PoX v2 contract,
 ///   so this should surface in a panic.
 pub fn pox_lock_extend_v2(

pox-locking/src/pox_3.rs

@@ -95,7 +95,7 @@ pub fn pox_lock_v3(
 /// Returns Ok(lock_amount) when successful
 ///
 /// # Errors
-/// - Returns Error::PoxExtendNotLocked if this function was called on an account
+/// - Returns LockingError::PoxExtendNotLocked if this function was called on an account
 ///   which isn't locked. This *should* have been checked by the PoX v3 contract,
 ///   so this should surface in a panic.
 pub fn pox_lock_extend_v3(
@@ -131,7 +131,7 @@ pub fn pox_lock_extend_v3(
 /// Returns Ok( account snapshot ) when successful
 ///
 /// # Errors
-/// - Returns Error::PoxExtendNotLocked if this function was called on an account
+/// - Returns LockingError::PoxExtendNotLocked if this function was called on an account
 ///   which isn't locked. This *should* have been checked by the PoX v3 contract,
 ///   so this should surface in a panic.
 pub fn pox_lock_increase_v3(

pox-locking/src/pox_4.rs

@@ -68,7 +68,7 @@ pub fn pox_lock_v4(
 /// Returns Ok(lock_amount) when successful
 ///
 /// # Errors
-/// - Returns Error::PoxExtendNotLocked if this function was called on an account
+/// - Returns LockingError::PoxExtendNotLocked if this function was called on an account
 ///   which isn't locked. This *should* have been checked by the PoX v4 contract,
 ///   so this should surface in a panic.
 pub fn pox_lock_extend_v4(
@@ -104,7 +104,7 @@ pub fn pox_lock_extend_v4(
 /// Returns Ok( account snapshot ) when successful
 ///
 /// # Errors
-/// - Returns Error::PoxExtendNotLocked if this function was called on an account
+/// - Returns LockingError::PoxExtendNotLocked if this function was called on an account
 ///   which isn't locked. This *should* have been checked by the PoX v4 contract,
 ///   so this should surface in a panic.
 pub fn pox_lock_increase_v4(

stacks-codec/src/lib.rs

@@ -242,7 +242,7 @@ pub const MAX_PAYLOAD_LEN: u32 = 1 + 16 * 1024 * 1024;
 pub const MAX_MESSAGE_LEN: u32 =
     MAX_PAYLOAD_LEN + (PREAMBLE_ENCODED_SIZE + MAX_RELAYERS_LEN * RELAY_DATA_ENCODED_SIZE);
 
-/// P2P preamble length (addands correspond to fields above)
+/// P2P preamble length (addends correspond to the fields of `blockstack_lib::net::Preamble`, in order).
 pub const PREAMBLE_ENCODED_SIZE: u32 = 4
     + 4
     + 4

stacks-common/src/util/db.rs

@@ -48,8 +48,10 @@ pub fn update_lock_table(conn: &Connection) {
     LOCK_TABLE.lock().unwrap().insert(k, v);
 }
 
-/// Called by `rusqlite` if we are waiting too long on a database lock
-/// If called too many times, will assume a deadlock and panic
+/// Called by `rusqlite` if we are waiting too long on a database lock.
+/// Logs an error with a backtrace and the current `LOCK_TABLE` every
+/// ~5 minutes of accumulated waiting, then keeps sleeping and returning
+/// `true` so `rusqlite` retries the lock indefinitely.
 pub fn tx_busy_handler(run_count: i32) -> bool {
     const AVG_SLEEP_TIME_MS: u64 = 100;