Fix function rustdoc titles to use third person

Updates function documentation to follow the project's policy of using third person in rustdoc titles (e.g., "Encodes" instead of "Encode").

Fix more function rustdoc titles to use third person

docs: add policy for third-person function documentation

docs: fix whitespace issue in policy.md

Author: 0xZaddyy

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

@@ -62,7 +62,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.