Rename merkle_root functions

Recently we renamed the `hash` module to `merkle_root`, this makes the
public functions provided stutter if used with one layer of path as is
Rust convention:

 `merkle_root::bitcoin_merkle_root`

We can improve on this by renaming the functions to 'calculate', then we
get

- `merkle_root::calculate()`
- `merkle_root::calculate_inline()`

bitcoin/src/blockdata/block.rs

@@ -13,9 +13,8 @@ use crate::prelude::*;
 
 use core::fmt;
 
-use crate::util;
+use crate::{merkle_tree, util};
 use crate::util::Error::{BlockBadTarget, BlockBadProofOfWork};
-use crate::merkle_tree::bitcoin_merkle_root;
 use crate::hashes::{Hash, HashEngine};
 use crate::hash_types::{Wtxid, BlockHash, TxMerkleNode, WitnessMerkleNode, WitnessCommitment};
 use crate::consensus::{encode, Encodable, Decodable};
@@ -235,7 +234,7 @@ impl Block {
     /// Computes the transaction merkle root.
     pub fn compute_merkle_root(&self) -> Option<TxMerkleNode> {
         let hashes = self.txdata.iter().map(|obj| obj.txid().as_hash());
-        bitcoin_merkle_root(hashes).map(|h| h.into())
+        merkle_tree::calculate_root(hashes).map(|h| h.into())
     }
 
     /// Computes the witness commitment for the block's transaction list.
@@ -256,7 +255,7 @@ impl Block {
                 t.wtxid().as_hash()
             }
         });
-        bitcoin_merkle_root(hashes).map(|h| h.into())
+        merkle_tree::calculate_root(hashes).map(|h| h.into())
     }
 
     /// base_size == size of header + size of encoded transaction count.

bitcoin/src/merkle_tree.rs

@@ -3,6 +3,16 @@
 
 //! Bitcoin merkle tree functions.
 //!
+//! # Examples
+//!
+//! ```
+//! # use bitcoin::{merkle_tree, Txid};
+//! # use bitcoin::hashes::Hash;
+//! # let tx1 = Txid::all_zeros();  // Dummy hash values.
+//! # let tx2 = Txid::all_zeros();
+//! let tx_hashes = vec![tx1, tx2]; // All the hashes we wish to merkelize.
+//! let root = merkle_tree::calculate_root(tx_hashes.into_iter());
+//! ```
 
 use core::iter;
 
@@ -16,13 +26,13 @@ use crate::consensus::encode::Encodable;
 
 /// Calculates the merkle root of a list of *hashes*, inline (in place) in `hashes`.
 ///
-/// In most cases, you'll want to use [bitcoin_merkle_root] instead.
+/// In most cases, you'll want to use [`calculate_root`] instead.
 ///
 /// # 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.
-pub fn bitcoin_merkle_root_inline<T>(hashes: &mut [T]) -> Option<T>
+pub fn calculate_root_inline<T>(hashes: &mut [T]) -> Option<T>
 where
     T: Hash + Encodable,
           <T as Hash>::Engine: io::Write,
@@ -40,7 +50,7 @@ where
 /// - `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.
-pub fn bitcoin_merkle_root<T, I>(mut hashes: I) -> Option<T>
+pub fn calculate_root<T, I>(mut hashes: I) -> Option<T>
 where
     T: Hash + Encodable,
     <T as Hash>::Engine: io::Write,
@@ -116,8 +126,8 @@ mod tests {
             hashes_array[i] = hash;
         }
 
-        let from_iter = bitcoin_merkle_root(hashes_iter);
+        let from_iter = calculate_root(hashes_iter);
-        let from_array = bitcoin_merkle_root_inline(&mut hashes_array);
+        let from_array = calculate_root_inline(&mut hashes_array);
         assert_eq!(from_iter, from_array);
     }
 }

bitcoin/src/util/merkleblock.rs

@@ -528,9 +528,8 @@ mod tests {
     use secp256k1::rand::prelude::*;
 
     use crate::consensus::encode::{deserialize, serialize};
-    use crate::merkle_tree::bitcoin_merkle_root;
     use crate::util::merkleblock::{MerkleBlock, PartialMerkleTree};
-    use crate::Block;
+    use crate::{merkle_tree, Block};
 
     /// accepts `pmt_test_$num`
     fn pmt_test_from_name(name: &str) {
@@ -559,7 +558,7 @@ mod tests {
 
         // Calculate the merkle root and height
         let hashes = tx_ids.iter().map(|t| t.as_hash());
-        let merkle_root_1: TxMerkleNode = bitcoin_merkle_root(hashes).expect("hashes is not empty").into();
+        let merkle_root_1: TxMerkleNode = merkle_tree::calculate_root(hashes).expect("hashes is not empty").into();
         let mut height = 1;
         let mut ntx = tx_count;
         while ntx > 1 {

bitcoin/src/util/mod.rs

@@ -98,27 +98,27 @@ pub use crate::bip158;
 pub mod hash {
     use crate::consensus::encode::Encodable;
     use crate::hashes::Hash;
-    use crate::io;
+    use crate::{io, merkle_tree};
 
     /// Calculates the merkle root of a list of *hashes*, inline (in place) in `hashes`.
-    #[deprecated(since = "0.30.0", note = "Please use crate::merkle_tree::bitcoin_merkle_root_inline")]
+    #[deprecated(since = "0.30.0", note = "Please use crate::merkle_tree::calculate_root_inline")]
     pub fn bitcoin_merkle_root_inline<T>(hashes: &mut [T]) -> Option<T>
     where
         T: Hash + Encodable,
     <T as Hash>::Engine: io::Write,
     {
-        crate::merkle_tree::bitcoin_merkle_root_inline(hashes)
+        crate::merkle_tree::calculate_root_inline(hashes)
     }
 
     /// Calculates the merkle root of an iterator of *hashes*.
-    #[deprecated(since = "0.30.0", note = "Please use crate::merkle_tree::bitcoin_merkle_root")]
+    #[deprecated(since = "0.30.0", note = "Please use crate::merkle_tree::calculate_root")]
     pub fn bitcoin_merkle_root<T, I>(hashes: I) -> Option<T>
     where
         T: Hash + Encodable,
     <T as Hash>::Engine: io::Write,
         I: Iterator<Item=T>,
     {
-        crate::merkle_tree::bitcoin_merkle_root(hashes)
+        merkle_tree::calculate_root(hashes)
     }
 }