From 11bb1ff6ff65e89d9f101ffb7d76ebc09a20d738 Mon Sep 17 00:00:00 2001
From: "jamil.lambert" <jamil.lambert@proton.me>
Date: Thu, 23 May 2024 12:28:24 +0100
Subject: [PATCH] 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<C: Verification>(
         self,
@@ -776,6 +777,7 @@ impl TapTweak for UntweakedPublicKey {
     ///  * G is the generator point
     ///
     /// # Returns
+    ///
     /// The tweaked key and its parity.
     fn tap_tweak<C: Verification>(
         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<C: Verification>(
         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.