Skip to content

Commit 6b1d663

Browse files
committed
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
1 parent 3722e25 commit 6b1d663

File tree

24 files changed

+82
-77
lines changed

24 files changed

+82
-77
lines changed

bitcoin/src/address/mod.rs

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -900,7 +900,7 @@ impl Address<NetworkUnchecked> {
900900
#[inline]
901901
pub fn assume_checked(self) -> Address { Address::from_inner(self.into_inner()) }
902902

903-
/// Parse a bech32 Address string
903+
/// Parses a bech32 Address string
904904
pub fn from_bech32_str(s: &str) -> Result<Address<NetworkUnchecked>, Bech32Error> {
905905
let (hrp, witness_version, data) =
906906
bech32::segwit::decode(s).map_err(|e| Bech32Error::ParseBech32(ParseBech32Error(e)))?;
@@ -913,7 +913,7 @@ impl Address<NetworkUnchecked> {
913913
Ok(Address::from_inner(inner))
914914
}
915915

916-
/// Parse a base58 Address string
916+
/// Parses a base58 Address string
917917
pub fn from_base58_str(s: &str) -> Result<Address<NetworkUnchecked>, Base58Error> {
918918
if s.len() > 50 {
919919
return Err(LegacyAddressTooLongError { length: s.len() }.into());

bitcoin/src/bip32.rs

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -410,7 +410,7 @@ pub struct DerivationPathIterator<'a> {
410410
}
411411

412412
impl<'a> DerivationPathIterator<'a> {
413-
/// Start a new [DerivationPathIterator] at the given child.
413+
/// Starts a new [DerivationPathIterator] at the given child.
414414
pub fn start_from(path: &'a DerivationPath, start: ChildNumber) -> DerivationPathIterator<'a> {
415415
DerivationPathIterator { base: path, next_child: Some(start) }
416416
}
@@ -447,25 +447,25 @@ impl DerivationPath {
447447
DerivationPath(path)
448448
}
449449

450-
/// Convert into a [DerivationPath] that is a child of this one.
450+
/// Converts into a [DerivationPath] that is a child of this one.
451451
pub fn into_child(self, cn: ChildNumber) -> DerivationPath {
452452
let mut path = self.0;
453453
path.push(cn);
454454
DerivationPath(path)
455455
}
456456

457-
/// Get an [Iterator] over the children of this [DerivationPath]
457+
/// Gets an [Iterator] over the children of this [DerivationPath]
458458
/// starting with the given [ChildNumber].
459459
pub fn children_from(&self, cn: ChildNumber) -> DerivationPathIterator<'_> {
460460
DerivationPathIterator::start_from(self, cn)
461461
}
462462

463-
/// Get an [Iterator] over the unhardened children of this [DerivationPath].
463+
/// Gets an [Iterator] over the unhardened children of this [DerivationPath].
464464
pub fn normal_children(&self) -> DerivationPathIterator<'_> {
465465
DerivationPathIterator::start_from(self, ChildNumber::Normal { index: 0 })
466466
}
467467

468-
/// Get an [Iterator] over the hardened children of this [DerivationPath].
468+
/// Gets an [Iterator] over the hardened children of this [DerivationPath].
469469
pub fn hardened_children(&self) -> DerivationPathIterator<'_> {
470470
DerivationPathIterator::start_from(self, ChildNumber::Hardened { index: 0 })
471471
}
@@ -930,7 +930,7 @@ impl Xpub {
930930
Ok(pk)
931931
}
932932

933-
/// Compute the scalar tweak added to this key to get a child key
933+
/// Computes the scalar tweak added to this key to get a child key
934934
pub fn ckd_pub_tweak(
935935
&self,
936936
i: ChildNumber,

bitcoin/src/consensus/encode.rs

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -55,7 +55,7 @@ pub fn deserialize<T: Decodable>(data: &[u8]) -> Result<T, DeserializeError> {
5555
}
5656
}
5757

58-
/// Deserialize any decodable type from a hex string, will error if said deserialization
58+
/// Deserializes any decodable type from a hex string, will error if said deserialization
5959
/// doesn't consume the entire vector.
6060
pub fn deserialize_hex<T: Decodable>(hex: &str) -> Result<T, FromHexError> {
6161
let iter = hex::HexSliceToBytesIter::new(hex)?;
@@ -263,7 +263,7 @@ pub trait Encodable {
263263

264264
/// Data which can be encoded in a consensus-consistent way.
265265
pub trait Decodable: Sized {
266-
/// Decode `Self` from a size-limited reader.
266+
/// Decodes `Self` from a size-limited reader.
267267
///
268268
/// Like `consensus_decode` but relies on the reader being limited in the amount of data it
269269
/// returns, e.g. by being wrapped in [`std::io::Take`].
@@ -301,7 +301,7 @@ pub trait Decodable: Sized {
301301
Self::consensus_decode(reader)
302302
}
303303

304-
/// Decode an object with a well-defined format.
304+
/// Decodes an object with a well-defined format.
305305
///
306306
/// This is the method that should be implemented for a typical, fixed sized type
307307
/// implementing this trait. Default implementation is wrapping the reader

bitcoin/src/merkle_tree/block.rs

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -102,7 +102,7 @@ impl MerkleBlock {
102102
MerkleBlock { header: *header, txn: pmt }
103103
}
104104

105-
/// Extract the matching txid's represented by this partial Merkle tree
105+
/// Extracts the matching txid's represented by this partial Merkle tree
106106
/// and their respective indices within the partial tree.
107107
/// returns Ok(()) on success, or error in case of failure
108108
pub fn extract_matches(
@@ -235,7 +235,7 @@ impl PartialMerkleTree {
235235
pmt
236236
}
237237

238-
/// Extract the matching txid's represented by this partial Merkle tree
238+
/// Extracts the matching txid's represented by this partial Merkle tree
239239
/// and their respective indices within the partial tree.
240240
/// returns the Merkle root, or error in case of failure
241241
pub fn extract_matches(
@@ -297,7 +297,7 @@ impl PartialMerkleTree {
297297
(self.num_transactions + (1 << height) - 1) >> height
298298
}
299299

300-
/// Calculate the hash of a node in the Merkle tree (at leaf level: the txid's themselves)
300+
/// Calculates the hash of a node in the Merkle tree (at leaf level: the txid's themselves)
301301
fn calc_hash(&self, height: u32, pos: u32, txids: &[Txid]) -> TxMerkleNode {
302302
if height == 0 {
303303
// Hash at height 0 is the txid itself

bitcoin/src/pow.rs

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -824,7 +824,7 @@ impl U256 {
824824
f.pad_integral(true, "", s)
825825
}
826826

827-
/// Convert self to f64.
827+
/// Converts self to f64.
828828
#[inline]
829829
fn to_f64(self) -> f64 {
830830
// Reference: https://blog.m-ou.se/floats/

bitcoin/src/psbt/serialize.rs

Lines changed: 7 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -28,28 +28,28 @@ use crate::witness::Witness;
2828
/// A trait for serializing a value as raw data for insertion into PSBT
2929
/// key-value maps.
3030
pub(crate) trait Serialize {
31-
/// Serialize a value as raw data.
31+
/// Serializes a value as raw data.
3232
fn serialize(&self) -> Vec<u8>;
3333
}
3434

3535
/// A trait for deserializing a value from raw data in PSBT key-value maps.
3636
pub(crate) trait Deserialize: Sized {
37-
/// Deserialize a value from raw data.
37+
/// Deserializes a value from raw data.
3838
fn deserialize(bytes: &[u8]) -> Result<Self, Error>;
3939
}
4040

4141
impl Psbt {
42-
/// Serialize a value as bytes in hex.
42+
/// Serializes a value as bytes in hex.
4343
pub fn serialize_hex(&self) -> String { self.serialize().to_lower_hex_string() }
4444

45-
/// Serialize as raw binary data
45+
/// Serializes as raw binary data
4646
pub fn serialize(&self) -> Vec<u8> {
4747
let mut buf: Vec<u8> = Vec::new();
4848
self.serialize_to_writer(&mut buf).expect("Writing to Vec can't fail");
4949
buf
5050
}
5151

52-
/// Serialize the PSBT into a writer.
52+
/// Serializes the PSBT into a writer.
5353
pub fn serialize_to_writer(&self, w: &mut impl Write) -> io::Result<usize> {
5454
let mut written_len = 0;
5555

@@ -75,12 +75,12 @@ impl Psbt {
7575
Ok(written_len)
7676
}
7777

78-
/// Deserialize a value from raw binary data.
78+
/// Deserializes a value from raw binary data.
7979
pub fn deserialize(mut bytes: &[u8]) -> Result<Self, Error> {
8080
Self::deserialize_from_reader(&mut bytes)
8181
}
8282

83-
/// Deserialize a value from raw binary data read from a `BufRead` object.
83+
/// Deserializes a value from raw binary data read from a `BufRead` object.
8484
pub fn deserialize_from_reader<R: io::BufRead>(r: &mut R) -> Result<Self, Error> {
8585
const MAGIC_BYTES: &[u8] = b"psbt";
8686

bitcoin/src/sign_message.rs

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -100,7 +100,7 @@ mod message_signing {
100100
MessageSignature { signature, compressed }
101101
}
102102

103-
/// Serialize to bytes.
103+
/// Serializes to bytes.
104104
pub fn serialize(&self) -> [u8; 65] {
105105
let (recid, raw) = self.signature.serialize_compact();
106106
let mut serialized = [0u8; 65];
@@ -143,7 +143,7 @@ mod message_signing {
143143
Ok(PublicKey { inner: pubkey, compressed: self.compressed })
144144
}
145145

146-
/// Verify that the signature signs the message and was signed by the given address.
146+
/// Verifies that the signature signs the message and was signed by the given address.
147147
///
148148
/// To get the message hash from a message, use [super::signed_msg_hash].
149149
pub fn is_signed_by_address<C: secp256k1::Verification>(
@@ -172,7 +172,7 @@ mod message_signing {
172172
use crate::prelude::String;
173173

174174
impl MessageSignature {
175-
/// Convert a signature from base64 encoding.
175+
/// Converts a signature from base64 encoding.
176176
pub fn from_base64(s: &str) -> Result<MessageSignature, MessageSignatureError> {
177177
if s.len() != 88 {
178178
return Err(MessageSignatureError::InvalidLength);
@@ -184,7 +184,7 @@ mod message_signing {
184184
MessageSignature::from_byte_array(&byte_array).map_err(MessageSignatureError::from)
185185
}
186186

187-
/// Convert to base64 encoding.
187+
/// Converts to base64 encoding.
188188
pub fn to_base64(self) -> String { BASE64_STANDARD.encode(self.serialize()) }
189189
}
190190

chacha20_poly1305/src/chacha20.rs

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -193,7 +193,7 @@ impl State {
193193
[a, b, c, d]
194194
}
195195

196-
/// Perform a round on "columns" and then "diagonals" of the state.
196+
/// Performs a round on "columns" and then "diagonals" of the state.
197197
///
198198
/// 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]`.
199199
/// 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 {
222222
[a, b, c, d]
223223
}
224224

225-
/// Transform the state by performing the ChaCha block function.
225+
/// Transforms the state by performing the ChaCha block function.
226226
#[inline(always)]
227227
fn chacha_block(&mut self) {
228228
let mut working_state = self.matrix;
@@ -276,7 +276,7 @@ impl ChaCha20 {
276276
ChaCha20 { key, nonce, block_count: block, seek_offset_bytes: 0 }
277277
}
278278

279-
/// Get the keystream for a specific block.
279+
/// Gets the keystream for a specific block.
280280
#[inline(always)]
281281
fn keystream_at_block(&self, block: u32) -> [u8; 64] {
282282
let mut state = State::new(self.key, self.nonce, block);
@@ -331,16 +331,16 @@ impl ChaCha20 {
331331
}
332332
}
333333

334-
/// Get the keystream for specified block.
334+
/// Gets the keystream for specified block.
335335
pub fn get_keystream(&self, block: u32) -> [u8; 64] { self.keystream_at_block(block) }
336336

337-
/// Update the index of the keystream to the given byte.
337+
/// Updates the index of the keystream to the given byte.
338338
pub fn seek(&mut self, seek: u32) {
339339
self.block_count = seek / 64;
340340
self.seek_offset_bytes = (seek % 64) as usize;
341341
}
342342

343-
/// Update the index of the keystream to a block.
343+
/// Updates the index of the keystream to a block.
344344
pub fn block(&mut self, block: u32) {
345345
self.block_count = block;
346346
self.seek_offset_bytes = 0;

chacha20_poly1305/src/poly1305.rs

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -27,7 +27,7 @@ pub struct Poly1305 {
2727
}
2828

2929
impl Poly1305 {
30-
/// Initialize authenticator with a 32-byte one-time secret key.
30+
/// Initializes authenticator with a 32-byte one-time secret key.
3131
pub const fn new(key: [u8; 32]) -> Self {
3232
// Taken from Donna. Assigns r to a 26-bit 5-limb number while simultaneously 'clamping' r.
3333
let r0 = u32::from_le_bytes([key[0], key[1], key[2], key[3]]) & 0x3ffffff;
@@ -50,7 +50,7 @@ impl Poly1305 {
5050
}
5151
}
5252

53-
/// Add message to be authenticated, can be called multiple times before creating tag.
53+
/// Adds message to be authenticated, can be called multiple times before creating tag.
5454
pub fn input(&mut self, message: &[u8]) {
5555
// Process previous leftovers if the message is long enough to fill the leftovers buffer. If
5656
// 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 {
9595
}
9696
}
9797

98-
/// Generate authentication tag.
98+
/// Generates authentication tag.
9999
pub fn tag(mut self) -> [u8; 16] {
100100
// Add any remaining leftovers to accumulator.
101101
if self.leftovers_len > 0 {

consensus_encoding/src/encode/mod.rs

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -62,7 +62,7 @@ macro_rules! encoder_newtype{
6262
}
6363
}
6464

65-
/// Encode an object into a hash engine.
65+
/// Encodes an object into a hash engine.
6666
///
6767
/// Consumes and returns the hash engine to make it easier to call
6868
/// [`hashes::HashEngine::finalize`] directly on the result.

0 commit comments

Comments
 (0)