From d432a4ffad7bdbd3d51f8febfdd0dae7746bfb10 Mon Sep 17 00:00:00 2001 From: "Tobin C. Harding" Date: Wed, 4 Oct 2023 15:28:09 +1100 Subject: [PATCH 1/6] Fix rendered module docs Currently we have docs for public modules in two places and these are joined together when rendered as HTML. Remove the rustdoc strings from `lib.rs` and defer to the modules for the module level docs. --- src/hrp.rs | 2 ++ src/lib.rs | 3 --- 2 files changed, 2 insertions(+), 3 deletions(-) diff --git a/src/hrp.rs b/src/hrp.rs index cf161f3df..7a1631a14 100644 --- a/src/hrp.rs +++ b/src/hrp.rs @@ -1,4 +1,6 @@ // SPDX-License-Identifier: MIT +//! Re-exports the hrp types from [`primitives::hrp`] to make importing ergonomic for the top level APIs. + #[doc(inline)] pub use crate::primitives::hrp::{Hrp, BC, BCRT, TB}; diff --git a/src/lib.rs b/src/lib.rs index 033cbf3e1..acd3ba841 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -141,11 +141,8 @@ extern crate alloc; extern crate core; mod error; -/// Re-exports the hrp types from [`primitives::hrp`] to make importing ergonomic for the top level APIs. pub mod hrp; -/// All the primitive types and functionality used in encoding and decoding. pub mod primitives; -/// API for encoding and decoding segwit addresses. pub mod segwit; #[cfg(all(feature = "alloc", not(feature = "std"), not(test)))] From 9f7c21ac02e09a659f6087b24fe1ad6bd5694380 Mon Sep 17 00:00:00 2001 From: "Tobin C. Harding" Date: Fri, 20 Oct 2023 11:26:40 +1100 Subject: [PATCH 2/6] Fix links Fix the links by doing: - Use correct number, 350 not 359. - Make rustdoc render the links correctly, currently they are being rendered as the URL because it requires whitespace between body of rustdoc and link target. --- src/hrp.rs | 2 ++ src/primitives/mod.rs | 2 +- 2 files changed, 3 insertions(+), 1 deletion(-) diff --git a/src/hrp.rs b/src/hrp.rs index 7a1631a14..562ff1634 100644 --- a/src/hrp.rs +++ b/src/hrp.rs @@ -1,6 +1,8 @@ // SPDX-License-Identifier: MIT //! Re-exports the hrp types from [`primitives::hrp`] to make importing ergonomic for the top level APIs. +//! +//! [`primitives::hrp`]: crate::primitives::hrp #[doc(inline)] pub use crate::primitives::hrp::{Hrp, BC, BCRT, TB}; diff --git a/src/primitives/mod.rs b/src/primitives/mod.rs index 3041986ec..50463dc3a 100644 --- a/src/primitives/mod.rs +++ b/src/primitives/mod.rs @@ -24,7 +24,7 @@ pub enum Bech32 {} /// The bech32m checksum algorithm, defined in [BIP-350]. /// -/// [BIP-350]: +/// [BIP-350]: #[derive(Copy, Clone, PartialEq, Eq, PartialOrd, Ord, Hash)] pub enum Bech32m {} From 521d96338cb3f589c622449772b7736deb5ee866 Mon Sep 17 00:00:00 2001 From: "Tobin C. Harding" Date: Wed, 4 Oct 2023 15:41:25 +1100 Subject: [PATCH 3/6] Fix incorrect HRP docs Fix cut'n'pasta error, this is the `hrp` struct not an hrpstring. --- src/primitives/hrp.rs | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/src/primitives/hrp.rs b/src/primitives/hrp.rs index e5a67a204..0a2371174 100644 --- a/src/primitives/hrp.rs +++ b/src/primitives/hrp.rs @@ -191,7 +191,7 @@ impl Hrp { #[allow(clippy::len_without_is_empty)] // HRP is never empty. pub fn len(&self) -> usize { self.size } - /// Returns `true` if this [`Hrp`] is valid according to the bips. + /// Returns `true` if this HRP is valid according to the bips. /// /// [BIP-173] states that the HRP must be either "bc" or "tb". /// @@ -201,19 +201,19 @@ impl Hrp { self.is_valid_on_mainnet() || self.is_valid_on_testnet() } - /// Returns `true` if this hrpstring is valid on the Bitcoin network i.e., HRP is "bc". + /// Returns `true` if this HRP is valid on the Bitcoin network i.e., HRP is "bc". #[inline] pub fn is_valid_on_mainnet(&self) -> bool { *self == self::BC } - /// Returns `true` if this hrpstring is valid on the Bitcoin testnet network i.e., HRP is "tb". + /// Returns `true` if this HRP is valid on the Bitcoin testnet network i.e., HRP is "tb". #[inline] pub fn is_valid_on_testnet(&self) -> bool { *self == self::TB } - /// Returns `true` if this hrpstring is valid on the Bitcoin signet network i.e., HRP is "tb". + /// Returns `true` if this HRP is valid on the Bitcoin signet network i.e., HRP is "tb". #[inline] pub fn is_valid_on_signet(&self) -> bool { *self == self::TB } - /// Returns `true` if this hrpstring is valid on the Bitcoin regtest network i.e., HRP is "bcrt". + /// Returns `true` if this HRP is valid on the Bitcoin regtest network i.e., HRP is "bcrt". #[inline] pub fn is_valid_on_regtest(&self) -> bool { *self == self::BCRT } } From 628093553ba8a68991433a315f640a00dd93bad3 Mon Sep 17 00:00:00 2001 From: "Tobin C. Harding" Date: Wed, 4 Oct 2023 15:47:29 +1100 Subject: [PATCH 4/6] Update "crate level API" docs This line is a bit stale, since it was written we have added multiple crate level APIs. Use the same wording as in the `decode` module docs. --- src/primitives/encode.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/primitives/encode.rs b/src/primitives/encode.rs index 4790143d1..83fa76f6b 100644 --- a/src/primitives/encode.rs +++ b/src/primitives/encode.rs @@ -7,7 +7,7 @@ //! prepending HRP strings etc. //! //! In general, directly using these adaptors is not very ergonomic, and users are recommended to -//! instead use the higher-level functions at the root of this crate. +//! instead use the higher crate level API. //! //! WARNING: This module does not enforce the maximum length of an encoded bech32 string (90 chars). //! From 8dec93d90ccab9d6595d42f58a2048489318c7ed Mon Sep 17 00:00:00 2001 From: "Tobin C. Harding" Date: Thu, 5 Oct 2023 10:00:38 +1100 Subject: [PATCH 5/6] Drop docs usage of "higher" The wording is a bit iffy, fix it up. --- src/primitives/decode.rs | 2 +- src/primitives/encode.rs | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/src/primitives/decode.rs b/src/primitives/decode.rs index 95ab57d1e..89a7edb93 100644 --- a/src/primitives/decode.rs +++ b/src/primitives/decode.rs @@ -5,7 +5,7 @@ //! You should only need to use this module directly if you want control over exactly what is //! checked and when it is checked (correct bech32 characters, valid checksum, valid checksum for //! specific checksum algorithm, etc). If you are parsing/validating modern (post BIP-350) bitcoin -//! segwit addresses consider using the higher crate level API. +//! segwit addresses consider using the [`crate::segwit`] API. //! //! If you do find yourself using this module directly then consider using the most general type //! that serves your purposes, each type can be created by parsing an address string to `new`. You diff --git a/src/primitives/encode.rs b/src/primitives/encode.rs index 83fa76f6b..4020fbbfd 100644 --- a/src/primitives/encode.rs +++ b/src/primitives/encode.rs @@ -7,7 +7,7 @@ //! prepending HRP strings etc. //! //! In general, directly using these adaptors is not very ergonomic, and users are recommended to -//! instead use the higher crate level API. +//! instead use the crate level API. //! //! WARNING: This module does not enforce the maximum length of an encoded bech32 string (90 chars). //! From ea97465565cab18601665467a5a27493ec776594 Mon Sep 17 00:00:00 2001 From: "Tobin C. Harding" Date: Tue, 17 Oct 2023 15:12:22 +1100 Subject: [PATCH 6/6] Remove backticks for bip names Bips don't need code ticks (by convention). Also the ticks do not match up with the link so in HTML they are not links. --- src/segwit.rs | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/segwit.rs b/src/segwit.rs index facaa86e5..14476c36a 100644 --- a/src/segwit.rs +++ b/src/segwit.rs @@ -89,8 +89,8 @@ pub fn decode(s: &str) -> Result<(Hrp, Fe32, Vec), DecodeError> { /// Does validity checks on the `witness_version`, length checks on the `witness_program`, and /// checks the total encoded string length. /// -/// As specified by [`BIP-350`] we use the [`Bech32m`] checksum algorithm for witness versions 1 and -/// above, and for witness version 0 we use the original ([`BIP-173`]) [`Bech32`] checksum +/// As specified by [BIP-350] we use the [`Bech32m`] checksum algorithm for witness versions 1 and +/// above, and for witness version 0 we use the original ([BIP-173]) [`Bech32`] checksum /// algorithm. /// /// See also [`encode_v0`] or [`encode_v1`].