From 233a9133d82bb90f9e57f7a56d87b719d94b99f1 Mon Sep 17 00:00:00 2001 From: "jamil.lambert" Date: Thu, 23 May 2024 11:33:18 +0100 Subject: [PATCH 1/4] Standardize function doc Panics Changed the function docs to have the same format of /// /// # Panics /// /// description --- bitcoin/src/blockdata/script/owned.rs | 2 +- bitcoin/src/blockdata/script/push_bytes.rs | 2 +- bitcoin/src/merkle_tree/block.rs | 2 ++ bitcoin/src/psbt/mod.rs | 2 +- bitcoin/src/taproot/serialized_signature.rs | 2 +- units/src/amount.rs | 26 +++++++++++++++++---- 6 files changed, 27 insertions(+), 9 deletions(-) diff --git a/bitcoin/src/blockdata/script/owned.rs b/bitcoin/src/blockdata/script/owned.rs index d7189488c..e8558929b 100644 --- a/bitcoin/src/blockdata/script/owned.rs +++ b/bitcoin/src/blockdata/script/owned.rs @@ -241,7 +241,7 @@ impl ScriptBuf { /// Add a single instruction to the script. /// - /// ## Panics + /// # Panics /// /// The method panics if the instruction is a data push with length greater or equal to /// 0x100000000. diff --git a/bitcoin/src/blockdata/script/push_bytes.rs b/bitcoin/src/blockdata/script/push_bytes.rs index 5b0667113..1b229489a 100644 --- a/bitcoin/src/blockdata/script/push_bytes.rs +++ b/bitcoin/src/blockdata/script/push_bytes.rs @@ -235,7 +235,7 @@ mod primitive { /// Remove the byte at `index` and return it. /// - /// ## Panics + /// # Panics /// /// This method panics if `index` is out of bounds. #[track_caller] diff --git a/bitcoin/src/merkle_tree/block.rs b/bitcoin/src/merkle_tree/block.rs index 59c64969c..3639f6a30 100644 --- a/bitcoin/src/merkle_tree/block.rs +++ b/bitcoin/src/merkle_tree/block.rs @@ -216,6 +216,8 @@ impl PartialMerkleTree { /// The `txids` are the transaction hashes of the block and the `matches` is the contains flags /// wherever a tx hash should be included in the proof. /// + /// # Panics + /// /// Panics when `txids` is empty or when `matches` has a different length /// /// # Examples diff --git a/bitcoin/src/psbt/mod.rs b/bitcoin/src/psbt/mod.rs index bdfb62579..713dc2481 100644 --- a/bitcoin/src/psbt/mod.rs +++ b/bitcoin/src/psbt/mod.rs @@ -71,7 +71,7 @@ impl Psbt { /// /// The function returns error when UTXO information is not present or is invalid. /// - /// ## Panics + /// # Panics /// /// The function panics if the length of transaction inputs is not equal to the length of PSBT inputs. pub fn iter_funding_utxos(&self) -> impl Iterator> { diff --git a/bitcoin/src/taproot/serialized_signature.rs b/bitcoin/src/taproot/serialized_signature.rs index 4def2e578..290a16da7 100644 --- a/bitcoin/src/taproot/serialized_signature.rs +++ b/bitcoin/src/taproot/serialized_signature.rs @@ -133,7 +133,7 @@ impl<'a> TryFrom<&'a SerializedSignature> for Signature { impl SerializedSignature { /// Creates `SerializedSignature` from data and length. /// - /// ## Panics + /// # Panics /// /// If `len` > `MAX_LEN` #[inline] diff --git a/units/src/amount.rs b/units/src/amount.rs index a356fb440..6562585ba 100644 --- a/units/src/amount.rs +++ b/units/src/amount.rs @@ -886,7 +886,7 @@ impl Amount { /// Convert from a value expressing integer values of bitcoins to an [Amount] /// in const context. /// - /// ## Panics + /// # Panics /// /// The function panics if the argument multiplied by the number of sats /// per bitcoin overflows a u64 type. @@ -1046,12 +1046,20 @@ impl Amount { /// Unchecked addition. /// - /// Computes `self + rhs`. Panics in debug mode, wraps in release mode. + /// Computes `self + rhs`. + /// + /// # Panics + /// + /// On overflow, panics in debug mode, wraps in release mode. pub fn unchecked_add(self, rhs: Amount) -> Amount { Self(self.0 + rhs.0) } /// Unchecked subtraction. /// - /// Computes `self - rhs`. Panics in debug mode, wraps in release mode. + /// Computes `self - rhs`. + /// + /// # Panics + /// + /// On overflow, panics in debug mode, wraps in release mode. pub fn unchecked_sub(self, rhs: Amount) -> Amount { Self(self.0 - rhs.0) } /// Convert to a signed amount. @@ -1434,12 +1442,20 @@ impl SignedAmount { /// Unchecked addition. /// - /// Computes `self + rhs`. Panics in debug mode, wraps in release mode. + /// Computes `self + rhs`. + /// + /// # Panics + /// + /// On overflow, panics in debug mode, wraps in release mode. pub fn unchecked_add(self, rhs: SignedAmount) -> SignedAmount { Self(self.0 + rhs.0) } /// Unchecked subtraction. /// - /// Computes `self - rhs`. Panics in debug mode, wraps in release mode. + /// Computes `self - rhs`. + /// + /// # Panics + /// + /// On overflow, panics in debug mode, wraps in release mode. pub fn unchecked_sub(self, rhs: SignedAmount) -> SignedAmount { Self(self.0 - rhs.0) } /// Subtraction that doesn't allow negative [SignedAmount]s. From d219ceb68eb60e646e0daf2fe963c76839151464 Mon Sep 17 00:00:00 2001 From: "jamil.lambert" Date: Thu, 23 May 2024 11:38:32 +0100 Subject: [PATCH 2/4] Standardize function doc Examples Changed the function docs to have the same format of /// /// # Examples /// /// description --- bitcoin/src/bip158.rs | 1 + bitcoin/src/blockdata/locktime/absolute.rs | 6 ++++++ bitcoin/src/crypto/key.rs | 1 + internals/src/macros.rs | 2 +- units/src/amount.rs | 2 ++ units/src/locktime/absolute.rs | 2 ++ 6 files changed, 13 insertions(+), 1 deletion(-) diff --git a/bitcoin/src/bip158.rs b/bitcoin/src/bip158.rs index a820e9978..4d0bc4d38 100644 --- a/bitcoin/src/bip158.rs +++ b/bitcoin/src/bip158.rs @@ -480,6 +480,7 @@ impl<'a, R: BufRead + ?Sized> BitStreamReader<'a, R> { /// Reads nbit bits, returning the bits in a `u64` starting with the rightmost bit. /// /// # Examples + /// /// ``` /// # use bitcoin::bip158::BitStreamReader; /// # let data = vec![0xff]; diff --git a/bitcoin/src/blockdata/locktime/absolute.rs b/bitcoin/src/blockdata/locktime/absolute.rs index 548bf8e30..52669d8ab 100644 --- a/bitcoin/src/blockdata/locktime/absolute.rs +++ b/bitcoin/src/blockdata/locktime/absolute.rs @@ -45,6 +45,7 @@ pub use units::locktime::absolute::{ /// * [BIP-113 Median time-past as endpoint for lock-time calculations](https://github.com/bitcoin/bips/blob/master/bip-0113.mediawiki) /// /// # Examples +/// /// ``` /// # use bitcoin::absolute::{LockTime, LockTime::*}; /// # let n = LockTime::from_consensus(741521); // n OP_CHECKLOCKTIMEVERIFY @@ -61,6 +62,7 @@ pub enum LockTime { /// A block height lock time value. /// /// # Examples + /// /// ```rust /// use bitcoin::absolute::LockTime; /// @@ -73,6 +75,7 @@ pub enum LockTime { /// A UNIX timestamp lock time value. /// /// # Examples + /// /// ```rust /// use bitcoin::absolute::LockTime; /// @@ -141,6 +144,7 @@ impl LockTime { /// See [`LOCK_TIME_THRESHOLD`] for definition of a valid height value. /// /// # Examples + /// /// ```rust /// # use bitcoin::absolute::LockTime; /// assert!(LockTime::from_height(741521).is_ok()); @@ -157,6 +161,7 @@ impl LockTime { /// See [`LOCK_TIME_THRESHOLD`] for definition of a valid time value. /// /// # Examples + /// /// ```rust /// # use bitcoin::absolute::LockTime; /// assert!(LockTime::from_time(1653195600).is_ok()); @@ -196,6 +201,7 @@ impl LockTime { /// `height`/`time` is valid. /// /// # Examples + /// /// ```no_run /// # use bitcoin::absolute::{LockTime, Height, Time}; /// // Can be implemented if block chain data is available. diff --git a/bitcoin/src/crypto/key.rs b/bitcoin/src/crypto/key.rs index 5d8abc6a5..0c0f9d2d4 100644 --- a/bitcoin/src/crypto/key.rs +++ b/bitcoin/src/crypto/key.rs @@ -710,6 +710,7 @@ pub type UntweakedKeypair = Keypair; /// Tweaked BIP-340 key pair /// /// # Examples +/// /// ``` /// # #[cfg(feature = "rand-std")] { /// # use bitcoin::key::{Keypair, TweakedKeypair, TweakedPublicKey}; diff --git a/internals/src/macros.rs b/internals/src/macros.rs index 715f9cb78..4478c3545 100644 --- a/internals/src/macros.rs +++ b/internals/src/macros.rs @@ -122,7 +122,7 @@ macro_rules! const_assert { /// /// Note: Paths are not supported (for ex. impl_from_infallible!(Hello). /// -/// ## Examples +/// # Examples /// /// ```rust /// # use core::fmt::{Display, Debug}; diff --git a/units/src/amount.rs b/units/src/amount.rs index 6562585ba..98e8216c8 100644 --- a/units/src/amount.rs +++ b/units/src/amount.rs @@ -21,6 +21,7 @@ use internals::write_err; /// A set of denominations in which amounts can be expressed. /// /// # Examples +/// /// ``` /// # use core::str::FromStr; /// # use bitcoin_units::Amount; @@ -939,6 +940,7 @@ impl Amount { /// Please be aware of the risk of using floating-point numbers. /// /// # Examples + /// /// ``` /// # use bitcoin_units::amount::{Amount, Denomination}; /// let amount = Amount::from_sat(100_000); diff --git a/units/src/locktime/absolute.rs b/units/src/locktime/absolute.rs index f786c0b6c..49e1499d0 100644 --- a/units/src/locktime/absolute.rs +++ b/units/src/locktime/absolute.rs @@ -51,6 +51,7 @@ impl Height { /// If `n` does not represent a valid block height value. /// /// # Examples + /// /// ```rust /// use bitcoin_units::locktime::absolute::Height; /// @@ -146,6 +147,7 @@ impl Time { /// If `n` does not encode a valid UNIX time stamp. /// /// # Examples + /// /// ```rust /// use bitcoin_units::locktime::absolute::Time; /// From df83016c98bdcb069c1579d9f1fa7f74139214c0 Mon Sep 17 00:00:00 2001 From: "jamil.lambert" Date: Thu, 23 May 2024 12:15:40 +0100 Subject: [PATCH 3/4] Standardize function doc Errors Changed the function docs to have the same format of /// /// # Errors /// /// description --- bitcoin/src/blockdata/script/push_bytes.rs | 4 ++-- bitcoin/src/psbt/mod.rs | 8 +++---- bitcoin/src/psbt/raw.rs | 1 + bitcoin/src/taproot/merkle_branch.rs | 2 ++ bitcoin/src/taproot/mod.rs | 27 +++++++++++++++++----- 5 files changed, 30 insertions(+), 12 deletions(-) diff --git a/bitcoin/src/blockdata/script/push_bytes.rs b/bitcoin/src/blockdata/script/push_bytes.rs index 1b229489a..63b613bc2 100644 --- a/bitcoin/src/blockdata/script/push_bytes.rs +++ b/bitcoin/src/blockdata/script/push_bytes.rs @@ -207,7 +207,7 @@ mod primitive { /// Try pushing a single byte. /// - /// ## Errors + /// # Errors /// /// This method fails if `self` would exceed the limit. #[allow(deprecated)] @@ -220,7 +220,7 @@ mod primitive { /// Try appending a slice to `PushBytesBuf` /// - /// ## Errors + /// # Errors /// /// This method fails if `self` would exceed the limit. pub fn extend_from_slice(&mut self, bytes: &[u8]) -> Result<(), PushBytesError> { diff --git a/bitcoin/src/psbt/mod.rs b/bitcoin/src/psbt/mod.rs index 713dc2481..c7a588755 100644 --- a/bitcoin/src/psbt/mod.rs +++ b/bitcoin/src/psbt/mod.rs @@ -67,7 +67,7 @@ impl Psbt { /// For each PSBT input that contains UTXO information `Ok` is returned containing that information. /// The order of returned items is same as the order of inputs. /// - /// ## Errors + /// # Errors /// /// The function returns error when UTXO information is not present or is invalid. /// @@ -140,7 +140,7 @@ impl Psbt { /// Extracts the [`Transaction`] from a [`Psbt`] by filling in the available signature information. /// - /// ## Errors + /// # Errors /// /// [`ExtractTxError`] variants will contain either the [`Psbt`] itself or the [`Transaction`] /// that was extracted. These can be extracted from the Errors in order to recover. @@ -151,7 +151,7 @@ impl Psbt { /// Extracts the [`Transaction`] from a [`Psbt`] by filling in the available signature information. /// - /// ## Errors + /// # Errors /// /// See [`extract_tx`]. /// @@ -703,7 +703,7 @@ impl Psbt { /// 'Fee' being the amount that will be paid for mining a transaction with the current inputs /// and outputs i.e., the difference in value of the total inputs and the total outputs. /// - /// ## Errors + /// # Errors /// /// - [`Error::MissingUtxo`] when UTXO information for any input is not present or is invalid. /// - [`Error::NegativeFee`] if calculated value is negative. diff --git a/bitcoin/src/psbt/raw.rs b/bitcoin/src/psbt/raw.rs index 65b350b3c..e782ca727 100644 --- a/bitcoin/src/psbt/raw.rs +++ b/bitcoin/src/psbt/raw.rs @@ -188,6 +188,7 @@ where /// Constructs a [`ProprietaryKey`] from a [`Key`]. /// /// # Errors + /// /// Returns [`Error::InvalidProprietaryKey`] if `key` does not start with `0xFC` byte. fn try_from(key: Key) -> Result { if key.type_value != 0xFC { diff --git a/bitcoin/src/taproot/merkle_branch.rs b/bitcoin/src/taproot/merkle_branch.rs index 79d6e36b3..0e5732669 100644 --- a/bitcoin/src/taproot/merkle_branch.rs +++ b/bitcoin/src/taproot/merkle_branch.rs @@ -66,6 +66,7 @@ impl TaprootMerkleBranch { /// Creates a merkle proof from list of hashes. /// /// # Errors + /// /// If inner proof length is more than [`TAPROOT_CONTROL_MAX_NODE_COUNT`] (128). #[inline] fn from_collection + Into>>( @@ -123,6 +124,7 @@ macro_rules! impl_try_from { /// Creates a merkle proof from list of hashes. /// /// # Errors + /// /// If inner proof length is more than [`TAPROOT_CONTROL_MAX_NODE_COUNT`] (128). #[inline] fn try_from(v: $from) -> Result { diff --git a/bitcoin/src/taproot/mod.rs b/bitcoin/src/taproot/mod.rs index cfb843c9c..dc3de6e73 100644 --- a/bitcoin/src/taproot/mod.rs +++ b/bitcoin/src/taproot/mod.rs @@ -429,8 +429,13 @@ impl TaprootBuilder { Ok(TaprootBuilder { branch: vec![Some(node)] }) } - /// Adds a leaf script at `depth` to the builder with script version `ver`. Errors if the leaves - /// are not provided in DFS walk order. The depth of the root node is 0. + /// Adds a leaf script at `depth` to the builder with script version `ver`. + /// + /// The depth of the root node is 0. + /// + /// # Errors + /// + /// Errors if the leaves are not provided in DFS walk order. pub fn add_leaf_with_ver( self, depth: u8, @@ -441,16 +446,26 @@ impl TaprootBuilder { self.insert(leaf, depth) } - /// Adds a leaf script at `depth` to the builder with default script version. Errors if the - /// leaves are not provided in DFS walk order. The depth of the root node is 0. + /// Adds a leaf script at `depth` to the builder with default script version. + /// + /// The depth of the root node is 0. /// /// See [`TaprootBuilder::add_leaf_with_ver`] for adding a leaf with specific version. + /// + /// # Errors + /// + /// Errors if the leaves are not provided in DFS walk order. pub fn add_leaf(self, depth: u8, script: ScriptBuf) -> Result { self.add_leaf_with_ver(depth, script, LeafVersion::TapScript) } - /// Adds a hidden/omitted node at `depth` to the builder. Errors if the leaves are not provided - /// in DFS walk order. The depth of the root node is 0. + /// Adds a hidden/omitted node at `depth` to the builder. + /// + /// The depth of the root node is 0. + /// + /// # Errors + /// + /// Errors if the leaves are not provided in DFS walk order. pub fn add_hidden_node( self, depth: u8, From 11bb1ff6ff65e89d9f101ffb7d76ebc09a20d738 Mon Sep 17 00:00:00 2001 From: "jamil.lambert" Date: Thu, 23 May 2024 12:28:24 +0100 Subject: [PATCH 4/4] Standardize function doc Safety, Returns and Parameters Changed the function docs to have the same format of /// /// # Safety /// /// description --- bitcoin/src/blockdata/script/push_bytes.rs | 4 ++-- bitcoin/src/consensus/validation.rs | 4 ++++ bitcoin/src/crypto/key.rs | 3 +++ bitcoin/src/merkle_tree/mod.rs | 2 ++ bitcoin/src/psbt/mod.rs | 1 + 5 files changed, 12 insertions(+), 2 deletions(-) diff --git a/bitcoin/src/blockdata/script/push_bytes.rs b/bitcoin/src/blockdata/script/push_bytes.rs index 63b613bc2..1488ebb8e 100644 --- a/bitcoin/src/blockdata/script/push_bytes.rs +++ b/bitcoin/src/blockdata/script/push_bytes.rs @@ -46,7 +46,7 @@ mod primitive { impl PushBytes { /// Creates `&Self` without checking the length. /// - /// ## Safety + /// # Safety /// /// The caller is responsible for checking that the length is less than the [`LIMIT`]. unsafe fn from_slice_unchecked(bytes: &[u8]) -> &Self { @@ -55,7 +55,7 @@ mod primitive { /// Creates `&mut Self` without checking the length. /// - /// ## Safety + /// # Safety /// /// The caller is responsible for checking that the length is less than the [`LIMIT`]. unsafe fn from_mut_slice_unchecked(bytes: &mut [u8]) -> &mut Self { diff --git a/bitcoin/src/consensus/validation.rs b/bitcoin/src/consensus/validation.rs index 32b5d5d07..c5926ee90 100644 --- a/bitcoin/src/consensus/validation.rs +++ b/bitcoin/src/consensus/validation.rs @@ -21,6 +21,7 @@ use crate::consensus::encode; /// [`bitcoinconsensus::VERIFY_ALL`]. /// /// # Parameters +/// /// * `index` - The input index in spending which is spending this transaction. /// * `amount` - The amount this script guards. /// * `spending_tx` - The transaction that attempts to spend the output holding this script. @@ -38,6 +39,7 @@ pub fn verify_script( /// Verifies spend of an input script. /// /// # Parameters +/// /// * `index` - The input index in spending which is spending this transaction. /// * `amount` - The amount this script guards. /// * `spending_tx` - The transaction that attempts to spend the output holding this script. @@ -112,6 +114,7 @@ impl Script { /// Shorthand for [`Self::verify_with_flags`] with flag [`bitcoinconsensus::VERIFY_ALL`]. /// /// # Parameters + /// /// * `index` - The input index in spending which is spending this transaction. /// * `amount` - The amount this script guards. /// * `spending_tx` - The transaction that attempts to spend the output holding this script. @@ -129,6 +132,7 @@ impl Script { /// Verifies spend of an input script. /// /// # Parameters + /// /// * `index` - The input index in spending which is spending this transaction. /// * `amount` - The amount this script guards. /// * `spending_tx` - The transaction that attempts to spend the output holding this script. diff --git a/bitcoin/src/crypto/key.rs b/bitcoin/src/crypto/key.rs index 0c0f9d2d4..679ba8a04 100644 --- a/bitcoin/src/crypto/key.rs +++ b/bitcoin/src/crypto/key.rs @@ -747,6 +747,7 @@ pub trait TapTweak { /// * G is the generator point /// /// # Returns + /// /// The tweaked key and its parity. fn tap_tweak( self, @@ -776,6 +777,7 @@ impl TapTweak for UntweakedPublicKey { /// * G is the generator point /// /// # Returns + /// /// The tweaked key and its parity. fn tap_tweak( self, @@ -807,6 +809,7 @@ impl TapTweak for UntweakedKeypair { /// The public key is generated from a private key by multiplying with generator point, Q = qG. /// /// # Returns + /// /// The tweaked key and its parity. fn tap_tweak( self, diff --git a/bitcoin/src/merkle_tree/mod.rs b/bitcoin/src/merkle_tree/mod.rs index d26a27a84..d91a81e48 100644 --- a/bitcoin/src/merkle_tree/mod.rs +++ b/bitcoin/src/merkle_tree/mod.rs @@ -35,6 +35,7 @@ pub use self::block::{MerkleBlock, MerkleBlockError, PartialMerkleTree}; /// this method and should not be used again afterwards). /// /// # Returns +/// /// - `None` if `hashes` is empty. The merkle root of an empty tree of hashes is undefined. /// - `Some(hash)` if `hashes` contains one element. A single hash is by definition the merkle root. /// - `Some(merkle_root)` if length of `hashes` is greater than one. @@ -53,6 +54,7 @@ where /// Calculates the merkle root of an iterator of *hashes*. /// /// # Returns +/// /// - `None` if `hashes` is empty. The merkle root of an empty tree of hashes is undefined. /// - `Some(hash)` if `hashes` contains one element. A single hash is by definition the merkle root. /// - `Some(merkle_root)` if length of `hashes` is greater than one. diff --git a/bitcoin/src/psbt/mod.rs b/bitcoin/src/psbt/mod.rs index c7a588755..86f1f9b47 100644 --- a/bitcoin/src/psbt/mod.rs +++ b/bitcoin/src/psbt/mod.rs @@ -739,6 +739,7 @@ pub trait GetKey { /// Attempts to get the private key for `key_request`. /// /// # Returns + /// /// - `Some(key)` if the key is found. /// - `None` if the key was not found but no error was encountered. /// - `Err` if an error was encountered while looking for the key.