Merge rust-bitcoin#4975: Fix function rustdoc titles to use third person

6b1d663 Fix function rustdoc titles to use third person (oyindamola oladapo)

Pull request description:

  This PR Updates function documentation titles throughout the codebase to use third person instead of imperative mood Follows the project policy that function docs should use "Encodes a foobar" instead of "Encode a foobar"
  
  closes rust-bitcoin#4970


ACKs for top commit:
  apoelstra:
    ACK 6b1d663; successfully ran local tests


Tree-SHA512: d43d2d1b883ff3e5854b62aeda314a183354edca055b4707716609aaaddead99e0a70caf3389e84676b437613d79836b9c39659cae08727625ddbfe728aeeb31

Author: apoelstra

bitcoin/src/address/mod.rs

@@ -900,7 +900,7 @@ impl Address<NetworkUnchecked> {
     #[inline]
     pub fn assume_checked(self) -> Address { Address::from_inner(self.into_inner()) }
 
-    /// Parse a bech32 Address string
+    /// Parses a bech32 Address string
     pub fn from_bech32_str(s: &str) -> Result<Address<NetworkUnchecked>, Bech32Error> {
         let (hrp, witness_version, data) =
             bech32::segwit::decode(s).map_err(|e| Bech32Error::ParseBech32(ParseBech32Error(e)))?;
@@ -913,7 +913,7 @@ impl Address<NetworkUnchecked> {
         Ok(Address::from_inner(inner))
     }
 
-    /// Parse a base58 Address string
+    /// Parses a base58 Address string
     pub fn from_base58_str(s: &str) -> Result<Address<NetworkUnchecked>, Base58Error> {
         if s.len() > 50 {
             return Err(LegacyAddressTooLongError { length: s.len() }.into());

bitcoin/src/bip32.rs

@@ -410,7 +410,7 @@ pub struct DerivationPathIterator<'a> {
 }
 
 impl<'a> DerivationPathIterator<'a> {
-    /// Start a new [DerivationPathIterator] at the given child.
+    /// Starts a new [DerivationPathIterator] at the given child.
     pub fn start_from(path: &'a DerivationPath, start: ChildNumber) -> DerivationPathIterator<'a> {
         DerivationPathIterator { base: path, next_child: Some(start) }
     }
@@ -447,25 +447,25 @@ impl DerivationPath {
         DerivationPath(path)
     }
 
-    /// Convert into a [DerivationPath] that is a child of this one.
+    /// Converts into a [DerivationPath] that is a child of this one.
     pub fn into_child(self, cn: ChildNumber) -> DerivationPath {
         let mut path = self.0;
         path.push(cn);
         DerivationPath(path)
     }
 
-    /// Get an [Iterator] over the children of this [DerivationPath]
+    /// Gets an [Iterator] over the children of this [DerivationPath]
     /// starting with the given [ChildNumber].
     pub fn children_from(&self, cn: ChildNumber) -> DerivationPathIterator<'_> {
         DerivationPathIterator::start_from(self, cn)
     }
 
-    /// Get an [Iterator] over the unhardened children of this [DerivationPath].
+    /// Gets an [Iterator] over the unhardened children of this [DerivationPath].
     pub fn normal_children(&self) -> DerivationPathIterator<'_> {
         DerivationPathIterator::start_from(self, ChildNumber::Normal { index: 0 })
     }
 
-    /// Get an [Iterator] over the hardened children of this [DerivationPath].
+    /// Gets an [Iterator] over the hardened children of this [DerivationPath].
     pub fn hardened_children(&self) -> DerivationPathIterator<'_> {
         DerivationPathIterator::start_from(self, ChildNumber::Hardened { index: 0 })
     }
@@ -930,7 +930,7 @@ impl Xpub {
         Ok(pk)
     }
 
-    /// Compute the scalar tweak added to this key to get a child key
+    /// Computes the scalar tweak added to this key to get a child key
     pub fn ckd_pub_tweak(
         &self,
         i: ChildNumber,

bitcoin/src/consensus/encode.rs

@@ -55,7 +55,7 @@ pub fn deserialize<T: Decodable>(data: &[u8]) -> Result<T, DeserializeError> {
     }
 }
 
-/// Deserialize any decodable type from a hex string, will error if said deserialization
+/// Deserializes any decodable type from a hex string, will error if said deserialization
 /// doesn't consume the entire vector.
 pub fn deserialize_hex<T: Decodable>(hex: &str) -> Result<T, FromHexError> {
     let iter = hex::HexSliceToBytesIter::new(hex)?;
@@ -263,7 +263,7 @@ pub trait Encodable {
 
 /// Data which can be encoded in a consensus-consistent way.
 pub trait Decodable: Sized {
-    /// Decode `Self` from a size-limited reader.
+    /// Decodes `Self` from a size-limited reader.
     ///
     /// Like `consensus_decode` but relies on the reader being limited in the amount of data it
     /// returns, e.g. by being wrapped in [`std::io::Take`].
@@ -301,7 +301,7 @@ pub trait Decodable: Sized {
         Self::consensus_decode(reader)
     }
 
-    /// Decode an object with a well-defined format.
+    /// Decodes an object with a well-defined format.
     ///
     /// This is the method that should be implemented for a typical, fixed sized type
     /// implementing this trait. Default implementation is wrapping the reader

bitcoin/src/merkle_tree/block.rs

@@ -102,7 +102,7 @@ impl MerkleBlock {
         MerkleBlock { header: *header, txn: pmt }
     }
 
-    /// Extract the matching txid's represented by this partial Merkle tree
+    /// Extracts the matching txid's represented by this partial Merkle tree
     /// and their respective indices within the partial tree.
     /// returns Ok(()) on success, or error in case of failure
     pub fn extract_matches(
@@ -235,7 +235,7 @@ impl PartialMerkleTree {
         pmt
     }
 
-    /// Extract the matching txid's represented by this partial Merkle tree
+    /// Extracts the matching txid's represented by this partial Merkle tree
     /// and their respective indices within the partial tree.
     /// returns the Merkle root, or error in case of failure
     pub fn extract_matches(
@@ -297,7 +297,7 @@ impl PartialMerkleTree {
         (self.num_transactions + (1 << height) - 1) >> height
     }
 
-    /// Calculate the hash of a node in the Merkle tree (at leaf level: the txid's themselves)
+    /// Calculates the hash of a node in the Merkle tree (at leaf level: the txid's themselves)
     fn calc_hash(&self, height: u32, pos: u32, txids: &[Txid]) -> TxMerkleNode {
         if height == 0 {
             // Hash at height 0 is the txid itself

bitcoin/src/pow.rs

@@ -824,7 +824,7 @@ impl U256 {
         f.pad_integral(true, "", s)
     }
 
-    /// Convert self to f64.
+    /// Converts self to f64.
     #[inline]
     fn to_f64(self) -> f64 {
         // Reference: https://blog.m-ou.se/floats/

bitcoin/src/psbt/serialize.rs

@@ -28,28 +28,28 @@ use crate::witness::Witness;
 /// A trait for serializing a value as raw data for insertion into PSBT
 /// key-value maps.
 pub(crate) trait Serialize {
-    /// Serialize a value as raw data.
+    /// Serializes a value as raw data.
     fn serialize(&self) -> Vec<u8>;
 }
 
 /// A trait for deserializing a value from raw data in PSBT key-value maps.
 pub(crate) trait Deserialize: Sized {
-    /// Deserialize a value from raw data.
+    /// Deserializes a value from raw data.
     fn deserialize(bytes: &[u8]) -> Result<Self, Error>;
 }
 
 impl Psbt {
-    /// Serialize a value as bytes in hex.
+    /// Serializes a value as bytes in hex.
     pub fn serialize_hex(&self) -> String { self.serialize().to_lower_hex_string() }
 
-    /// Serialize as raw binary data
+    /// Serializes as raw binary data
     pub fn serialize(&self) -> Vec<u8> {
         let mut buf: Vec<u8> = Vec::new();
         self.serialize_to_writer(&mut buf).expect("Writing to Vec can't fail");
         buf
     }
 
-    /// Serialize the PSBT into a writer.
+    /// Serializes the PSBT into a writer.
     pub fn serialize_to_writer(&self, w: &mut impl Write) -> io::Result<usize> {
         let mut written_len = 0;
 
@@ -75,12 +75,12 @@ impl Psbt {
         Ok(written_len)
     }
 
-    /// Deserialize a value from raw binary data.
+    /// Deserializes a value from raw binary data.
     pub fn deserialize(mut bytes: &[u8]) -> Result<Self, Error> {
         Self::deserialize_from_reader(&mut bytes)
     }
 
-    /// Deserialize a value from raw binary data read from a `BufRead` object.
+    /// Deserializes a value from raw binary data read from a `BufRead` object.
     pub fn deserialize_from_reader<R: io::BufRead>(r: &mut R) -> Result<Self, Error> {
         const MAGIC_BYTES: &[u8] = b"psbt";
 

bitcoin/src/sign_message.rs

@@ -100,7 +100,7 @@ mod message_signing {
             MessageSignature { signature, compressed }
         }
 
-        /// Serialize to bytes.
+        /// Serializes to bytes.
         pub fn serialize(&self) -> [u8; 65] {
             let (recid, raw) = self.signature.serialize_compact();
             let mut serialized = [0u8; 65];
@@ -143,7 +143,7 @@ mod message_signing {
             Ok(PublicKey { inner: pubkey, compressed: self.compressed })
         }
 
-        /// Verify that the signature signs the message and was signed by the given address.
+        /// Verifies that the signature signs the message and was signed by the given address.
         ///
         /// To get the message hash from a message, use [super::signed_msg_hash].
         pub fn is_signed_by_address<C: secp256k1::Verification>(
@@ -172,7 +172,7 @@ mod message_signing {
         use crate::prelude::String;
 
         impl MessageSignature {
-            /// Convert a signature from base64 encoding.
+            /// Converts a signature from base64 encoding.
             pub fn from_base64(s: &str) -> Result<MessageSignature, MessageSignatureError> {
                 if s.len() != 88 {
                     return Err(MessageSignatureError::InvalidLength);
@@ -184,7 +184,7 @@ mod message_signing {
                 MessageSignature::from_byte_array(&byte_array).map_err(MessageSignatureError::from)
             }
 
-            /// Convert to base64 encoding.
+            /// Converts to base64 encoding.
             pub fn to_base64(self) -> String { BASE64_STANDARD.encode(self.serialize()) }
         }
 

chacha20_poly1305/src/chacha20.rs

@@ -193,7 +193,7 @@ impl State {
         [a, b, c, d]
     }
 
-    /// Perform a round on "columns" and then "diagonals" of the state.
+    /// Performs a round on "columns" and then "diagonals" of the state.
     ///
     /// The column quarter rounds are made up of indexes: `[0,4,8,12]`, `[1,5,9,13]`, `[2,6,10,14]`, `[3,7,11,15]`.
     /// The diagonals quarter rounds are made up of indexes: `[0,5,10,15]`, `[1,6,11,12]`, `[2,7,8,13]`, `[3,4,9,14]`.
@@ -222,7 +222,7 @@ impl State {
         [a, b, c, d]
     }
 
-    /// Transform the state by performing the ChaCha block function.
+    /// Transforms the state by performing the ChaCha block function.
     #[inline(always)]
     fn chacha_block(&mut self) {
         let mut working_state = self.matrix;
@@ -276,7 +276,7 @@ impl ChaCha20 {
         ChaCha20 { key, nonce, block_count: block, seek_offset_bytes: 0 }
     }
 
-    /// Get the keystream for a specific block.
+    /// Gets the keystream for a specific block.
     #[inline(always)]
     fn keystream_at_block(&self, block: u32) -> [u8; 64] {
         let mut state = State::new(self.key, self.nonce, block);
@@ -331,16 +331,16 @@ impl ChaCha20 {
         }
     }
 
-    /// Get the keystream for specified block.
+    /// Gets the keystream for specified block.
     pub fn get_keystream(&self, block: u32) -> [u8; 64] { self.keystream_at_block(block) }
 
-    /// Update the index of the keystream to the given byte.
+    /// Updates the index of the keystream to the given byte.
     pub fn seek(&mut self, seek: u32) {
         self.block_count = seek / 64;
         self.seek_offset_bytes = (seek % 64) as usize;
     }
 
-    /// Update the index of the keystream to a block.
+    /// Updates the index of the keystream to a block.
     pub fn block(&mut self, block: u32) {
         self.block_count = block;
         self.seek_offset_bytes = 0;

chacha20_poly1305/src/poly1305.rs

@@ -27,7 +27,7 @@ pub struct Poly1305 {
 }
 
 impl Poly1305 {
-    /// Initialize authenticator with a 32-byte one-time secret key.
+    /// Initializes authenticator with a 32-byte one-time secret key.
     pub const fn new(key: [u8; 32]) -> Self {
         // Taken from Donna. Assigns r to a 26-bit 5-limb number while simultaneously 'clamping' r.
         let r0 = u32::from_le_bytes([key[0], key[1], key[2], key[3]]) & 0x3ffffff;
@@ -50,7 +50,7 @@ impl Poly1305 {
         }
     }
 
-    /// Add message to be authenticated, can be called multiple times before creating tag.
+    /// Adds message to be authenticated, can be called multiple times before creating tag.
     pub fn input(&mut self, message: &[u8]) {
         // Process previous leftovers if the message is long enough to fill the leftovers buffer. If
         // the message is too short then it will just be added to the leftovers at the end. Now if there
@@ -95,7 +95,7 @@ impl Poly1305 {
         }
     }
 
-    /// Generate authentication tag.
+    /// Generates authentication tag.
     pub fn tag(mut self) -> [u8; 16] {
         // Add any remaining leftovers to accumulator.
         if self.leftovers_len > 0 {

consensus_encoding/src/encode/mod.rs

@@ -65,7 +65,7 @@ macro_rules! encoder_newtype{
     }
 }
 
-/// Encode an object into a hash engine.
+/// Encodes an object into a hash engine.
 ///
 /// Consumes and returns the hash engine to make it easier to call
 /// [`hashes::HashEngine::finalize`] directly on the result.