Check documentation intra-link (#1432)

* Fix broken links in rustdoc

This fixes all of the rustdoc warnings on nightly.

* Check documentation intra-link

* Fix config

* Fix bad indent

* Make nightly explicit

* More links fixes

* Fix link broken after master merge

Co-authored-by: Demi Obenour <48690212+DemiMarie-parity@users.noreply.github.com>

.circleci/config.yml

@@ -6,6 +6,7 @@ workflows:
     jobs:
       - test
       - test-wasm
+      - check-rustdoc-links
       - integration-test
 
 jobs:
@@ -40,6 +41,31 @@ jobs:
           paths:
             - "/cache"
 
+  check-rustdoc-links:
+    docker:
+      - image: rust:latest
+    steps:
+      - checkout
+      - restore_cache:
+          key: test-rustdoc-cache-{{ epoch }}
+      - run:
+          name: Install nightly Rust
+          # TODO: intra-doc links are available on nightly only
+          # see https://doc.rust-lang.org/nightly/rustdoc/lints.html#intra_doc_link_resolution_failure
+          command: rustup default nightly
+      - run:
+          name: Print Rust version
+          command: |
+            rustc --version
+      - run:
+          name: Check Rustdoc links
+          command: RUSTDOCFLAGS="--deny intra_doc_link_resolution_failure" cargo +nightly doc --verbose --workspace --no-deps --document-private-items
+      - save_cache:
+          key: test-rustdoc-cache-{{ epoch }}
+          paths:
+            - ./target
+            - /usr/local/cargo
+
   test-wasm:
     docker:
       - image: parity/rust-builder:latest

core/src/identity/rsa.rs

@@ -84,7 +84,7 @@ impl PublicKey {
     /// Encode the RSA public key in DER as a X.509 SubjectPublicKeyInfo structure,
     /// as defined in [RFC5280].
     ///
-    /// [RFC5280] https://tools.ietf.org/html/rfc5280#section-4.1
+    /// [RFC5280]: https://tools.ietf.org/html/rfc5280#section-4.1
     pub fn encode_x509(&self) -> Vec<u8> {
         let spki = Asn1SubjectPublicKeyInfo {
             algorithmIdentifier: Asn1RsaEncryption {

core/src/nodes/tasks.rs

@@ -22,7 +22,7 @@
 //!
 //! The core type is a [`task::Task`], which implements [`futures::Future`]
 //! and connects and handles a node. A task receives and sends messages
-//! ([`tasks::FromTaskMessage`], [`tasks::ToTaskMessage`]) to the outside.
+//! ([`task::FromTaskMessage`], [`task::ToTaskMessage`]) to the outside.
 //!
 //! A set of tasks is managed by a [`Manager`] which creates tasks when a
 //! node should be connected to (cf. [`Manager::add_reach_attempt`]) or

core/src/transport.rs

@@ -209,7 +209,7 @@ pub trait Transport {
     }
 
     /// Begins a series of protocol upgrades via an
-    /// [`upgrade::Builder`](core::transport::upgrade::Builder).
+    /// [`upgrade::Builder`](upgrade::Builder).
     fn upgrade(self, version: upgrade::Version) -> upgrade::Builder<Self>
     where
         Self: Sized,

core/src/transport/upgrade.rs

@@ -239,7 +239,7 @@ type EitherUpgrade<C, U> = future::Either<InboundUpgradeApply<C, U>, OutboundUpg
 
 /// An upgrade on an authenticated, non-multiplexed [`Transport`].
 ///
-/// See [`Builder::upgrade`](Builder::upgrade).
+/// See [`Transport::upgrade`]
 #[derive(Debug, Copy, Clone)]
 pub struct Upgrade<T, U> { inner: T, upgrade: U }
 

misc/multiaddr/src/lib.rs

@@ -105,7 +105,7 @@ impl Multiaddr {
         Some(protocol)
     }
 
-    /// Like [`push`] but consumes `self`.
+    /// Like [`Multiaddr::push`] but consumes `self`.
     pub fn with(mut self, p: Protocol<'_>) -> Self {
         let mut w = io::Cursor::<&mut Vec<u8>>::new(Arc::make_mut(&mut self.bytes));
         w.set_position(w.get_ref().len() as u64);

misc/multistream-select/src/length_delimited.rs

@@ -284,10 +284,10 @@ impl<R> LengthDelimitedReader<R> {
     /// # Panic
     ///
     /// Will panic if called while there is data in the read or write buffer.
-    /// The read buffer is guaranteed to be empty whenever `Stream::poll` yields
+    /// The read buffer is guaranteed to be empty whenever [`Stream::poll`] yields
     /// a new `Message`. The write buffer is guaranteed to be empty whenever
-    /// [`poll_write_buffer`] yields `Async::Ready` or after the `Sink` has been
-    /// completely flushed via [`Sink::poll_complete`].
+    /// [`LengthDelimited::poll_write_buffer`] yields [`Async::Ready`] or after
+    /// the [`Sink`] has been completely flushed via [`Sink::poll_complete`].
     pub fn into_inner(self) -> (R, BytesMut) {
         self.inner.into_inner()
     }

misc/multistream-select/src/negotiated.rs

@@ -62,7 +62,7 @@ impl<TInner: AsyncRead + AsyncWrite> Future for NegotiatedComplete<TInner> {
 }
 
 impl<TInner> Negotiated<TInner> {
-    /// Creates a `Negotiated` in state [`State::Complete`], possibly
+    /// Creates a `Negotiated` in state [`State::Completed`], possibly
     /// with `remaining` data to be sent.
     pub(crate) fn completed(io: TInner, remaining: BytesMut) -> Self {
         Negotiated { state: State::Completed { io, remaining } }

misc/multistream-select/src/protocol.rs

@@ -62,8 +62,8 @@ const MSG_LS: &[u8] = b"ls\n";
 pub enum Version {
     /// Version 1 of the multistream-select protocol. See [1] and [2].
     ///
-    /// [1] https://github.com/libp2p/specs/blob/master/connections/README.md#protocol-negotiation
-    /// [2] https://github.com/multiformats/multistream-select
+    /// [1]: https://github.com/libp2p/specs/blob/master/connections/README.md#protocol-negotiation
+    /// [2]: https://github.com/multiformats/multistream-select
     V1,
     /// A lazy variant of version 1 that is identical on the wire but delays
     /// sending of protocol negotiation data as much as possible.
@@ -302,7 +302,7 @@ impl<R> MessageIO<R> {
     ///
     /// Panics if the read buffer is not empty, meaning that an incoming
     /// protocol negotiation frame has been partially read. The read buffer
-    /// is guaranteed to be empty whenever [`MessageIO::poll`] returned
+    /// is guaranteed to be empty whenever `MessageIO::poll` returned
     /// a message.
     pub fn into_inner(self) -> (R, BytesMut) {
         self.inner.into_inner()
@@ -368,7 +368,7 @@ impl<R> MessageReader<R> {
     ///
     /// Panics if the read buffer is not empty, meaning that an incoming
     /// protocol negotiation frame has been partially read. The read buffer
-    /// is guaranteed to be empty whenever [`MessageReader::poll`] returned
+    /// is guaranteed to be empty whenever `MessageReader::poll` returned
     /// a message.
     pub fn into_inner(self) -> (R, BytesMut) {
         self.inner.into_inner()

misc/rw-stream-sink/src/lib.rs

@@ -23,7 +23,7 @@
 //! [`AsyncRead`] and [`AsyncWrite`].
 //!
 //! Each call to [`AsyncWrite::poll_write`] will send one packet to the sink.
-//! Calls to [`AsyncRead::read`] will read from the stream's incoming packets.
+//! Calls to [`AsyncRead::poll_read`] will read from the stream's incoming packets.
 
 use futures::{prelude::*, ready};
 use std::{io::{self, Read}, pin::Pin, task::{Context, Poll}};

muxers/yamux/src/lib.rs

@@ -37,7 +37,7 @@ impl<S> fmt::Debug for Yamux<S> {
 }
 
 struct Inner<S> {
-    /// The `futures::stream::Stream` of incoming substreams.
+    /// The [`futures::stream::Stream`] of incoming substreams.
     incoming: S,
     /// Handle to control the connection.
     control: yamux::Control,
@@ -171,7 +171,7 @@ impl Config {
         Config(cfg)
     }
 
-    /// Turn this into a `LocalConfig` for use with upgrades of !Send resources.
+    /// Turn this into a [`LocalConfig`] for use with upgrades of ![`Send`] resources.
     pub fn local(self) -> LocalConfig {
         LocalConfig(self)
     }
@@ -253,7 +253,7 @@ where
     }
 }
 
-/// The Yamux [`StreamMuxer`] error type.
+/// The Yamux [`libp2p_core::StreamMuxer`] error type.
 #[derive(Debug, Error)]
 #[error("yamux error: {0}")]
 pub struct YamuxError(#[from] pub yamux::ConnectionError);
@@ -316,4 +316,4 @@ impl<T> Stream for LocalIncoming<T> {
 }
 
 impl<T> Unpin for LocalIncoming<T> {
-}
+}

protocols/gossipsub/src/behaviour.rs

@@ -383,7 +383,7 @@ impl Gossipsub {
         debug!("Completed JOIN for topic: {:?}", topic_hash);
     }
 
-    /// Gossipsub LEAVE(topic) - Notifies mesh[topic] peers with PRUNE messages.
+    /// Gossipsub LEAVE(topic) - Notifies mesh\[topic\] peers with PRUNE messages.
     fn leave(&mut self, topic_hash: &TopicHash) {
         debug!("Running LEAVE for topic {:?}", topic_hash);
 
@@ -880,7 +880,7 @@ impl Gossipsub {
         }
     }
 
-    /// Helper function which forwards a message to mesh[topic] peers.
+    /// Helper function which forwards a message to mesh\[topic\] peers.
     fn forward_msg(&mut self, message: GossipsubMessage, source: &PeerId) {
         let msg_id = (self.config.message_id_fn)(&message);
         debug!("Forwarding message: {:?}", msg_id);

protocols/kad/src/behaviour.rs

@@ -471,7 +471,7 @@ where
     /// of the libp2p Kademlia provider API.
     ///
     /// The results of the (repeated) provider announcements sent by this node are
-    /// delivered in [`KademliaEvent::AddProviderResult`].
+    /// delivered in [`AddProviderResult`].
     pub fn start_providing(&mut self, key: record::Key) {
         let record = ProviderRecord::new(key.clone(), self.kbuckets.local_key().preimage().clone());
         if let Err(err) = self.store.add_provider(record) {
@@ -1435,7 +1435,7 @@ impl Quorum {
 
 /// The events produced by the `Kademlia` behaviour.
 ///
-/// See [`Kademlia::poll`].
+/// See [`NetworkBehaviour::poll`].
 #[derive(Debug)]
 pub enum KademliaEvent {
     /// The result of [`Kademlia::bootstrap`].

protocols/kad/src/jobs.rs

@@ -41,10 +41,10 @@
 //!
 //! This module implements two periodic jobs:
 //!
-//!   * [`jobs::PutRecordJob`]: For (re-)publication and (re-)replication of
+//!   * [`PutRecordJob`]: For (re-)publication and (re-)replication of
 //!     regular (value-)records.
 //!
-//!   * [`jobs::AddProviderJob`]: For (re-)publication of provider records.
+//!   * [`AddProviderJob`]: For (re-)publication of provider records.
 //!     Provider records currently have no separate replication mechanism.
 //!
 //! A periodic job is driven like a `Future` or `Stream` by `poll`ing it.

protocols/kad/src/kbucket.rs

@@ -32,12 +32,11 @@
 //! an [`AppliedPending`] result which must be consumed by calling [`take_applied_pending`]
 //! regularly and / or after performing lookup operations like [`entry`] and [`closest`].
 //!
-//! [`entry`]: kbucket::KBucketsTable::entry
-//! [`closest`]: kbucket::KBucketsTable::closest
-//! [`AppliedPending`]: kbucket::AppliedPending
-//! [`KBucketsTable`]: kbucket::KBucketsTable
-//! [`take_applied_pending`]: kbucket::KBucketsTable::take_applied_pending
-//! [`PendingEntry`]: kbucket::PendingEntry
+//! [`entry`]: KBucketsTable::entry
+//! [`closest`]: KBucketsTable::closest
+//! [`AppliedPending`]: bucket::AppliedPending
+//! [`take_applied_pending`]: KBucketsTable::take_applied_pending
+//! [`PendingEntry`]: entry::PendingEntry
 
 // [Implementation Notes]
 //
@@ -469,7 +468,7 @@ where
     /// Together with a known key `a` (e.g. the local key), a random distance `d` for
     /// this bucket w.r.t `k` gives rise to the corresponding (random) key `b` s.t.
     /// the XOR distance between `a` and `b` is `d`. In other words, it gives
-    /// rise to a random key falling into this bucket. See [`Key::from_distance`].
+    /// rise to a random key falling into this bucket. See [`key::Key::for_distance`].
     pub fn rand_distance(&self, rng: &mut impl rand::Rng) -> Distance {
         self.index.rand_distance(rng)
     }

protocols/kad/src/protocol.rs

@@ -25,10 +25,6 @@
 //! The upgrade's output is a `Sink + Stream` of messages. The `Stream` component is used
 //! to poll the underlying transport for incoming messages, and the `Sink` component
 //! is used to send messages to remote peers.
-//!
-//! [`KademliaProtocolConfig`]: protocol::KademliaProtocolConfig
-//! [`KadRequestMsg`]: protocol::KadRequestMsg
-//! [`KadResponseMsg`]: protocol::KadResponseMsg
 
 use bytes::BytesMut;
 use codec::UviBytes;

protocols/kad/src/query/peers.rs

@@ -36,7 +36,7 @@
 //!
 //! A peer iterator can be finished prematurely at any time through `finish`.
 //!
-//! [`Finished`]: peers::PeersIterState::Finished
+//! [`Finished`]: PeersIterState::Finished
 
 pub mod closest;
 pub mod fixed;

protocols/noise/src/lib.rs

@@ -297,7 +297,7 @@ where
 ///
 /// On success, the upgrade yields the [`PeerId`] obtained from the
 /// `RemoteIdentity`. The output of this upgrade is thus directly suitable
-/// for creating an [`authenticated`](libp2p_core::TransportBuilder::authenticate)
+/// for creating an [`authenticated`](libp2p_core::transport::upgrade::Authenticate)
 /// transport for use with a [`Network`](libp2p_core::nodes::Network).
 #[derive(Clone)]
 pub struct NoiseAuthenticated<P, C: Zeroize, R> {

protocols/ping/src/handler.rs

@@ -102,8 +102,8 @@ impl PingConfig {
     /// at any time, i.e. in the absence of ping failures the connection lifetime
     /// is determined by other protocol handlers.
     ///
-    /// If the maximum  number of allowed ping failures is reached, the
-    /// connection is always terminated as a result of [`PingHandler::poll`]
+    /// If the maximum number of allowed ping failures is reached, the
+    /// connection is always terminated as a result of [`ProtocolsHandler::poll`]
     /// returning an error, regardless of the keep-alive setting.
     pub fn with_keep_alive(mut self, b: bool) -> Self {
         self.keep_alive = b;

protocols/ping/src/lib.rs

@@ -38,7 +38,7 @@
 //! > it only adds an additional condition for terminating the connection, namely
 //! > a certain number of failed ping requests.
 //!
-//! [`Swarm`]: libp2p_core::Swarm
+//! [`Swarm`]: libp2p_swarm::Swarm
 //! [`Transport`]: libp2p_core::Transport
 
 pub mod protocol;

protocols/secio/src/lib.rs

@@ -25,7 +25,7 @@
 //!
 //! The `SecioConfig` implements [`InboundUpgrade`] and [`OutboundUpgrade`] and thus
 //! serves as a connection upgrade for authentication of a transport.
-//! See [`authenticate`](libp2p_core::transport::upgrade::builder::Builder::authenticate).
+//! See [`authenticate`](libp2p_core::transport::upgrade::Builder::authenticate).
 //!
 //! ```no_run
 //! # fn main() {

swarm/src/behaviour.rs

@@ -155,11 +155,11 @@ pub trait NetworkBehaviour: Send + 'static {
 
 /// Parameters passed to `poll()`, that the `NetworkBehaviour` has access to.
 pub trait PollParameters {
-    /// Iterator returned by [`supported_protocols`].
+    /// Iterator returned by [`supported_protocols`](PollParameters::supported_protocols).
     type SupportedProtocolsIter: ExactSizeIterator<Item = Vec<u8>>;
-    /// Iterator returned by [`listened_addresses`].
+    /// Iterator returned by [`listened_addresses`](PollParameters::listened_addresses).
     type ListenedAddressesIter: ExactSizeIterator<Item = Multiaddr>;
-    /// Iterator returned by [`external_addresses`].
+    /// Iterator returned by [`external_addresses`](PollParameters::external_addresses).
     type ExternalAddressesIter: ExactSizeIterator<Item = Multiaddr>;
 
     /// Returns the list of protocol the behaviour supports when a remote negotiates a protocol on
@@ -190,6 +190,8 @@ pub trait NetworkBehaviourEventProcess<TEvent> {
 
 /// An action that a [`NetworkBehaviour`] can trigger in the [`Swarm`]
 /// in whose context it is executing.
+///
+/// [`Swarm`]: super::Swarm
 #[derive(Debug, Clone)]
 pub enum NetworkBehaviourAction<TInEvent, TOutEvent> {
     /// Instructs the `Swarm` to return an event when it is being polled.

swarm/src/protocols_handler.rs

@@ -75,14 +75,14 @@ pub use select::{IntoProtocolsHandlerSelect, ProtocolsHandlerSelect};
 /// Communication with a remote over a set of protocols is initiated in one of two ways:
 ///
 ///   1. Dialing by initiating a new outbound substream. In order to do so,
-///      [`ProtocolsHandler::poll()`] must return an [`OutboundSubstreamRequest`], providing an
-///      instance of [`ProtocolsHandler::OutboundUpgrade`] that is used to negotiate the
+///      [`ProtocolsHandler::poll()`] must return an [`ProtocolsHandlerEvent::OutboundSubstreamRequest`],
+///      providing an instance of [`libp2p_core::upgrade::OutboundUpgrade`] that is used to negotiate the
 ///      protocol(s). Upon success, [`ProtocolsHandler::inject_fully_negotiated_outbound`]
 ///      is called with the final output of the upgrade.
 ///
 ///   2. Listening by accepting a new inbound substream. When a new inbound substream
 ///      is created on a connection, [`ProtocolsHandler::listen_protocol`] is called
-///      to obtain an instance of [`ProtocolsHandler::InboundUpgrade`] that is used to
+///      to obtain an instance of [`libp2p_core::upgrade::InboundUpgrade`] that is used to
 ///      negotiate the protocol(s). Upon success,
 ///      [`ProtocolsHandler::inject_fully_negotiated_inbound`] is called with the final
 ///      output of the upgrade.
@@ -111,8 +111,8 @@ pub trait ProtocolsHandler: Send + 'static {
     /// The type of additional information passed to an `OutboundSubstreamRequest`.
     type OutboundOpenInfo: Send + 'static;
 
-    /// The [`InboundUpgrade`] to apply on inbound substreams to negotiate the
-    /// desired protocols.
+    /// The [`InboundUpgrade`](libp2p_core::upgrade::InboundUpgrade) to apply on inbound
+    /// substreams to negotiate the desired protocols.
     ///
     /// > **Note**: The returned `InboundUpgrade` should always accept all the generally
     /// >           supported protocols, even if in a specific context a particular one is