From 81a704302cef373142ce07505945d928a8b68f11 Mon Sep 17 00:00:00 2001 From: "Tobin C. Harding" Date: Wed, 3 Apr 2024 11:09:47 +1100 Subject: [PATCH 1/3] Improve rustdocs on U256 type Improve the rustdocs on the private `U256` type by doing: - Remove link to self within constructors, just use backticks - Use `U256` instead of `Self` or `self` - Fix incorrect usage of `CompactTarget` [0] [0] We knew this was wrong when we merged it but because the docs are private we elected to do this follow up patch. --- bitcoin/src/pow.rs | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/bitcoin/src/pow.rs b/bitcoin/src/pow.rs index cfb3f342..027b3105 100644 --- a/bitcoin/src/pow.rs +++ b/bitcoin/src/pow.rs @@ -400,7 +400,7 @@ impl U256 { const ONE: U256 = U256(0, 1); - /// Creates a `U256` from an prefixed hex string. + /// Creates a `U256` from a prefixed hex string. fn from_hex(s: &str) -> Result { let stripped = if let Some(stripped) = s.strip_prefix("0x") { stripped @@ -412,7 +412,7 @@ impl U256 { Ok(U256::from_hex_internal(stripped)?) } - /// Creates a `CompactTarget` from an unprefixed hex string. + /// Creates a `U256` from an unprefixed hex string. fn from_unprefixed_hex(s: &str) -> Result { if s.starts_with("0x") || s.starts_with("0X") { return Err(ContainsPrefixError::new(s).into()); @@ -437,7 +437,7 @@ impl U256 { Ok(U256(high, low)) } - /// Creates [`U256`] from a big-endian array of `u8`s. + /// Creates `U256` from a big-endian array of `u8`s. #[cfg_attr(all(test, mutate), mutate)] fn from_be_bytes(a: [u8; 32]) -> U256 { let (high, low) = split_in_half(a); @@ -446,7 +446,7 @@ impl U256 { U256(big, little) } - /// Creates a [`U256`] from a little-endian array of `u8`s. + /// Creates a `U256` from a little-endian array of `u8`s. #[cfg_attr(all(test, mutate), mutate)] fn from_le_bytes(a: [u8; 32]) -> U256 { let (high, low) = split_in_half(a); @@ -455,7 +455,7 @@ impl U256 { U256(big, little) } - /// Converts `Self` to a big-endian array of `u8`s. + /// Converts `U256` to a big-endian array of `u8`s. #[cfg_attr(all(test, mutate), mutate)] fn to_be_bytes(self) -> [u8; 32] { let mut out = [0; 32]; @@ -464,7 +464,7 @@ impl U256 { out } - /// Converts `Self` to a little-endian array of `u8`s. + /// Converts `U256` to a little-endian array of `u8`s. #[cfg_attr(all(test, mutate), mutate)] fn to_le_bytes(self) -> [u8; 32] { let mut out = [0; 32]; @@ -515,7 +515,7 @@ impl U256 { /// Returns the low 128 bits. fn low_u128(&self) -> u128 { self.1 } - /// Returns `self` as a `u128` saturating to `u128::MAX` if `self` is too big. + /// Returns this `U256` as a `u128` saturating to `u128::MAX` if `self` is too big. // Matagen gives false positive because >= and > both return u128::MAX fn saturating_to_u128(&self) -> u128 { if *self > U256::from(u128::MAX) { From 19f70959e1b4ff5997010df662a268f2c47ba190 Mon Sep 17 00:00:00 2001 From: "Tobin C. Harding" Date: Wed, 3 Apr 2024 11:12:45 +1100 Subject: [PATCH 2/3] Document private from_hex_internal function Use a code comment to document the calling restrictions of private function `from_hex_internal`. (Code comment because comment is not well formed as per convention in this codebase.) --- bitcoin/src/pow.rs | 1 + 1 file changed, 1 insertion(+) diff --git a/bitcoin/src/pow.rs b/bitcoin/src/pow.rs index 027b3105..50c30ab6 100644 --- a/bitcoin/src/pow.rs +++ b/bitcoin/src/pow.rs @@ -420,6 +420,7 @@ impl U256 { Ok(U256::from_hex_internal(s)?) } + // Caller to ensure `s` does not contain a prefix. fn from_hex_internal(s: &str) -> Result { let (high, low) = if s.len() < 32 { let low = parse::hex_u128(s)?; From 1bb32febbdc00d878f03c73c3d07b32a29fac9b9 Mon Sep 17 00:00:00 2001 From: "Tobin C. Harding" Date: Wed, 3 Apr 2024 11:14:32 +1100 Subject: [PATCH 3/3] Use manual docs attributes Currently we are using `Self` (in backticks) in the docs to functions defined by the `do_iml` macro, this is a bit lazy, we can do better than that. Use `doc` attribute and the `$ty` macro variable to construct the docs to use the type name. --- bitcoin/src/pow.rs | 24 ++++++++++++++++++------ 1 file changed, 18 insertions(+), 6 deletions(-) diff --git a/bitcoin/src/pow.rs b/bitcoin/src/pow.rs index 50c30ab6..5dbb9482 100644 --- a/bitcoin/src/pow.rs +++ b/bitcoin/src/pow.rs @@ -24,29 +24,41 @@ use crate::error::{ContainsPrefixError, MissingPrefixError, ParseIntError, Prefi macro_rules! do_impl { ($ty:ident) => { impl $ty { - /// Creates `Self` from a prefixed hex string. + #[doc = "Creates `"] + #[doc = stringify!($ty)] + #[doc = "` from a prefixed hex string."] pub fn from_hex(s: &str) -> Result { Ok($ty(U256::from_hex(s)?)) } - /// Creates `Self` from an unprefixed hex string. + #[doc = "Creates `"] + #[doc = stringify!($ty)] + #[doc = "` from an unprefixed hex string."] pub fn from_unprefixed_hex(s: &str) -> Result { Ok($ty(U256::from_unprefixed_hex(s)?)) } - /// Creates `Self` from a big-endian byte array. + #[doc = "Creates `"] + #[doc = stringify!($ty)] + #[doc = "` from a big-endian byte array."] #[inline] pub fn from_be_bytes(bytes: [u8; 32]) -> $ty { $ty(U256::from_be_bytes(bytes)) } - /// Creates `Self` from a little-endian byte array. + #[doc = "Creates `"] + #[doc = stringify!($ty)] + #[doc = "` from a little-endian byte array."] #[inline] pub fn from_le_bytes(bytes: [u8; 32]) -> $ty { $ty(U256::from_le_bytes(bytes)) } - /// Converts `self` to a big-endian byte array. + #[doc = "Converts `"] + #[doc = stringify!($ty)] + #[doc = "` to a big-endian byte array."] #[inline] pub fn to_be_bytes(self) -> [u8; 32] { self.0.to_be_bytes() } - /// Converts `self` to a little-endian byte array. + #[doc = "Converts `"] + #[doc = stringify!($ty)] + #[doc = "` to a little-endian byte array."] #[inline] pub fn to_le_bytes(self) -> [u8; 32] { self.0.to_le_bytes() } }