Merge pull request #600 from RCasatta/doc_fixes

Fixes documentation intra-links and enforce it

.github/workflows/rust.yml

@@ -39,3 +39,18 @@ jobs:
       - name: Running test script
         env: ${{ matrix.env }}
         run: ./contrib/test.sh
+
+  Docs:
+    name: Docs
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout Crate
+        uses: actions/checkout@v2
+      - name: Checkout Toolchain
+        uses: actions-rs/toolchain@v1
+        with:
+          profile: minimal
+          toolchain: stable
+          override: true
+      - name: Create Doc
+        run: cargo doc

src/blockdata/opcodes.rs

@@ -196,41 +196,41 @@ pub mod all {
     pub const OP_PUSHDATA2: All = All {code: 0x4d};
     /// Read the next 4 bytes as N; push the next N bytes as an array onto the stack
     pub const OP_PUSHDATA4: All = All {code: 0x4e};
-    /// Push the array [0x81] onto the stack
+    /// Push the array `0x81` onto the stack
     pub const OP_PUSHNUM_NEG1: All = All {code: 0x4f};
     /// Synonym for OP_RETURN
     pub const OP_RESERVED: All = All {code: 0x50};
-    /// Push the array [0x01] onto the stack
+    /// Push the array `0x01` onto the stack
     pub const OP_PUSHNUM_1: All = All {code: 0x51};
-    /// Push the array [0x02] onto the stack
+    /// Push the array `0x02` onto the stack
     pub const OP_PUSHNUM_2: All = All {code: 0x52};
-    /// Push the array [0x03] onto the stack
+    /// Push the array `0x03` onto the stack
     pub const OP_PUSHNUM_3: All = All {code: 0x53};
-    /// Push the array [0x04] onto the stack
+    /// Push the array `0x04` onto the stack
     pub const OP_PUSHNUM_4: All = All {code: 0x54};
-    /// Push the array [0x05] onto the stack
+    /// Push the array `0x05` onto the stack
     pub const OP_PUSHNUM_5: All = All {code: 0x55};
-    /// Push the array [0x06] onto the stack
+    /// Push the array `0x06` onto the stack
     pub const OP_PUSHNUM_6: All = All {code: 0x56};
-    /// Push the array [0x07] onto the stack
+    /// Push the array `0x07` onto the stack
     pub const OP_PUSHNUM_7: All = All {code: 0x57};
-    /// Push the array [0x08] onto the stack
+    /// Push the array `0x08` onto the stack
     pub const OP_PUSHNUM_8: All = All {code: 0x58};
-    /// Push the array [0x09] onto the stack
+    /// Push the array `0x09` onto the stack
     pub const OP_PUSHNUM_9: All = All {code: 0x59};
-    /// Push the array [0x0a] onto the stack
+    /// Push the array `0x0a` onto the stack
     pub const OP_PUSHNUM_10: All = All {code: 0x5a};
-    /// Push the array [0x0b] onto the stack
+    /// Push the array `0x0b` onto the stack
     pub const OP_PUSHNUM_11: All = All {code: 0x5b};
-    /// Push the array [0x0c] onto the stack
+    /// Push the array `0x0c` onto the stack
     pub const OP_PUSHNUM_12: All = All {code: 0x5c};
-    /// Push the array [0x0d] onto the stack
+    /// Push the array `0x0d` onto the stack
     pub const OP_PUSHNUM_13: All = All {code: 0x5d};
-    /// Push the array [0x0e] onto the stack
+    /// Push the array `0x0e` onto the stack
     pub const OP_PUSHNUM_14: All = All {code: 0x5e};
-    /// Push the array [0x0f] onto the stack
+    /// Push the array `0x0f` onto the stack
     pub const OP_PUSHNUM_15: All = All {code: 0x5f};
-    /// Push the array [0x10] onto the stack
+    /// Push the array `0x10` onto the stack
     pub const OP_PUSHNUM_16: All = All {code: 0x60};
     /// Does nothing
     pub const OP_NOP: All = All {code: 0x61};
@@ -385,9 +385,9 @@ pub mod all {
     pub const OP_HASH256: All = All {code: 0xaa};
     /// Ignore this and everything preceding when deciding what to sign when signature-checking
     pub const OP_CODESEPARATOR: All = All {code: 0xab};
-    /// https://en.bitcoin.it/wiki/OP_CHECKSIG pushing 1/0 for success/failure
+    /// <https://en.bitcoin.it/wiki/OP_CHECKSIG> pushing 1/0 for success/failure
     pub const OP_CHECKSIG: All = All {code: 0xac};
-    /// https://en.bitcoin.it/wiki/OP_CHECKSIG returning success/failure
+    /// <https://en.bitcoin.it/wiki/OP_CHECKSIG> returning success/failure
     pub const OP_CHECKSIGVERIFY: All = All {code: 0xad};
     /// Pop N, N pubkeys, M, M signatures, a dummy (due to bug in reference code), and verify that all M signatures are valid.
     /// Push 1 for "all valid", 0 otherwise
@@ -396,9 +396,9 @@ pub mod all {
     pub const OP_CHECKMULTISIGVERIFY: All = All {code: 0xaf};
     /// Does nothing
     pub const OP_NOP1: All = All {code: 0xb0};
-    /// https://github.com/bitcoin/bips/blob/master/bip-0065.mediawiki
+    /// <https://github.com/bitcoin/bips/blob/master/bip-0065.mediawiki>
     pub const OP_CLTV: All = All {code: 0xb1};
-    /// https://github.com/bitcoin/bips/blob/master/bip-0112.mediawiki
+    /// <https://github.com/bitcoin/bips/blob/master/bip-0112.mediawiki>
     pub const OP_CSV: All = All {code: 0xb2};
     /// Does nothing
     pub const OP_NOP4: All = All {code: 0xb3};

src/blockdata/script.rs

@@ -431,7 +431,7 @@ impl Script {
     /// iterator will end. To instead iterate over the script as sequence of bytes, treat
     /// it as a slice using `script[..]` or convert it to a vector using `into_bytes()`.
     ///
-    /// To force minimal pushes, use [instructions_minimal].
+    /// To force minimal pushes, use [Self::instructions_minimal].
     pub fn instructions(&self) -> Instructions {
         Instructions {
             data: &self.0[..],

src/blockdata/transaction.rs

@@ -697,7 +697,7 @@ impl SigHashType {
      /// Reads a 4-byte uint32 as a sighash type.
      ///
      /// **Note**: this replicates consensus behaviour, for current standardness rules correctness
-     /// you probably want [from_u32_standard].
+     /// you probably want [Self::from_u32_standard].
      pub fn from_u32_consensus(n: u32) -> SigHashType {
          // In Bitcoin Core, the SignatureHash function will mask the (int32) value with
          // 0x1f to (apparently) deactivate ACP when checking for SINGLE and NONE bits.

src/lib.rs

@@ -36,6 +36,7 @@
 #![deny(unused_imports)]
 #![deny(missing_docs)]
 #![deny(unused_must_use)]
+#![deny(broken_intra_doc_links)]
 
 // Re-exported dependencies.
 #[macro_use] pub extern crate bitcoin_hashes as hashes;

src/network/address.rs

@@ -48,7 +48,7 @@ impl Address {
     }
 
     /// Extract socket address from an [Address] message.
-    /// This will return [io::Error] [ErrorKind::AddrNotAvailable]
+    /// This will return [io::Error] [io::ErrorKind::AddrNotAvailable]
     /// if the message contains a Tor address.
     pub fn socket_addr(&self) -> Result<SocketAddr, io::Error> {
         let addr = &self.address;
@@ -249,7 +249,7 @@ pub struct AddrV2Message {
 
 impl AddrV2Message {
     /// Extract socket address from an [AddrV2Message] message.
-    /// This will return [io::Error] [ErrorKind::AddrNotAvailable]
+    /// This will return [io::Error] [io::ErrorKind::AddrNotAvailable]
     /// if the address type can't be converted into a [SocketAddr].
     pub fn socket_addr(&self) -> Result<SocketAddr, io::Error> {
         match self.addr {

src/network/message.rs

@@ -32,7 +32,7 @@ use network::message_filter;
 use consensus::encode::{CheckedData, Decodable, Encodable, VarInt, MAX_VEC_SIZE};
 use consensus::{encode, serialize};
 
-/// The maximum number of [Inventory] items in an `inv` message.
+/// The maximum number of [super::message_blockdata::Inventory] items in an `inv` message.
 ///
 /// This limit is not currently enforced by this implementation.
 pub const MAX_INV_SIZE: usize = 50_000;
@@ -187,7 +187,7 @@ impl NetworkMessage {
     ///
     /// This returns `"unknown"` for [NetworkMessage::Unknown],
     /// regardless of the actual command in the unknown message.
-    /// Use the [command] method to get the command for unknown messages.
+    /// Use the [Self::command] method to get the command for unknown messages.
     pub fn cmd(&self) -> &'static str {
         match *self {
             NetworkMessage::Version(_) => "version",
@@ -236,7 +236,7 @@ impl RawNetworkMessage {
     ///
     /// This returns `"unknown"` for [NetworkMessage::Unknown],
     /// regardless of the actual command in the unknown message.
-    /// Use the [command] method to get the command for unknown messages.
+    /// Use the [Self::command] method to get the command for unknown messages.
     pub fn cmd(&self) -> &'static str {
         self.payload.cmd()
     }

src/util/amount.rs

@@ -312,9 +312,9 @@ impl Amount {
     }
 
     /// Parses amounts with denomination suffix like they are produced with
-    /// [to_string_with_denomination] or with [fmt::Display].
+    /// [Self::to_string_with_denomination] or with [fmt::Display].
     /// If you want to parse only the amount without the denomination,
-    /// use [from_str_in].
+    /// use [Self::from_str_in].
     pub fn from_str_with_denomination(s: &str) -> Result<Amount, ParseAmountError> {
         let mut split = s.splitn(3, ' ');
         let amt_str = split.next().unwrap();
@@ -590,9 +590,9 @@ impl SignedAmount {
     }
 
     /// Parses amounts with denomination suffix like they are produced with
-    /// [to_string_with_denomination] or with [fmt::Display].
+    /// [Self::to_string_with_denomination] or with [fmt::Display].
     /// If you want to parse only the amount without the denomination,
-    /// use [from_str_in].
+    /// use [Self::from_str_in].
     pub fn from_str_with_denomination(s: &str) -> Result<SignedAmount, ParseAmountError> {
         let mut split = s.splitn(3, ' ');
         let amt_str = split.next().unwrap();
@@ -731,7 +731,7 @@ impl SignedAmount {
     }
 
     /// Subtraction that doesn't allow negative [SignedAmount]s.
-    /// Returns [None] if either [self], [rhs] or the result is strictly negative.
+    /// Returns [None] if either [self], `rhs` or the result is strictly negative.
     pub fn positive_sub(self, rhs: SignedAmount) -> Option<SignedAmount> {
         if self.is_negative() || rhs.is_negative() || rhs > self {
             None

src/util/bip32.rs

@@ -14,7 +14,7 @@
 //! BIP32 Implementation
 //!
 //! Implementation of BIP32 hierarchical deterministic wallets, as defined
-//! at https://github.com/bitcoin/bips/blob/master/bip-0032.mediawiki
+//! at <https://github.com/bitcoin/bips/blob/master/bip-0032.mediawiki>
 
 use std::default::Default;
 use std::{error, fmt};
@@ -304,7 +304,7 @@ impl FromStr for DerivationPath {
 
 /// An iterator over children of a [DerivationPath].
 ///
-/// It is returned by the methods [DerivationPath::children_since],
+/// It is returned by the methods [DerivationPath::children_from],
 /// [DerivationPath::normal_children] and [DerivationPath::hardened_children].
 pub struct DerivationPathIterator<'a> {
     base: &'a DerivationPath,

src/util/contracthash.rs

@@ -15,7 +15,7 @@
 //! Pay-to-contract-hash support
 //!
 //! See Appendix A of the Blockstream sidechains whitepaper
-//! at http://blockstream.com/sidechains.pdf for details of
+//! at <http://blockstream.com/sidechains.pdf> for details of
 //! what this does.
 
 #![cfg_attr(not(test), deprecated)]

src/util/misc.rs

@@ -128,7 +128,7 @@ mod message_signing {
 
         /// Attempt to recover a public key from the signature and the signed message.
         ///
-        /// To get the message hash from a message, use [signed_msg_hash].
+        /// To get the message hash from a message, use [super::signed_msg_hash].
         pub fn recover_pubkey<C: secp256k1::Verification>(
             &self,
             secp_ctx: &secp256k1::Secp256k1<C>,
@@ -144,7 +144,7 @@ mod message_signing {
 
         /// Verify that the signature signs the message and was signed by the given address.
         ///
-        /// To get the message hash from a message, use [signed_msg_hash].
+        /// To get the message hash from a message, use [super::signed_msg_hash].
         pub fn is_signed_by_address<C: secp256k1::Verification>(
             &self,
             secp_ctx: &secp256k1::Secp256k1<C>,

src/util/psbt/mod.rs

@@ -15,7 +15,7 @@
 //! # Partially Signed Transactions
 //!
 //! Implementation of BIP174 Partially Signed Bitcoin Transaction Format as
-//! defined at https://github.com/bitcoin/bips/blob/master/bip-0174.mediawiki
+//! defined at <https://github.com/bitcoin/bips/blob/master/bip-0174.mediawiki>
 //! except we define PSBTs containing non-standard SigHash types as invalid.
 
 use blockdata::script::Script;

src/util/psbt/raw.rs

@@ -15,7 +15,7 @@
 //! # Raw PSBT Key-Value Pairs
 //!
 //! Raw PSBT key-value pairs as defined at
-//! https://github.com/bitcoin/bips/blob/master/bip-0174.mediawiki.
+//! <https://github.com/bitcoin/bips/blob/master/bip-0174.mediawiki>.
 
 use std::{fmt, io};