diff --git a/.circleci/config.yml b/.circleci/config.yml index 08bcdcda..a56e2a40 100644 --- a/.circleci/config.yml +++ b/.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 diff --git a/core/src/identity/rsa.rs b/core/src/identity/rsa.rs index ea28f74f..7b699b08 100644 --- a/core/src/identity/rsa.rs +++ b/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 { let spki = Asn1SubjectPublicKeyInfo { algorithmIdentifier: Asn1RsaEncryption { diff --git a/core/src/nodes/tasks.rs b/core/src/nodes/tasks.rs index 5275121f..5d72fa22 100644 --- a/core/src/nodes/tasks.rs +++ b/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 diff --git a/core/src/transport.rs b/core/src/transport.rs index d9b900ab..d3ecea40 100644 --- a/core/src/transport.rs +++ b/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 where Self: Sized, diff --git a/core/src/transport/upgrade.rs b/core/src/transport/upgrade.rs index 64a182a6..b7ba5a16 100644 --- a/core/src/transport/upgrade.rs +++ b/core/src/transport/upgrade.rs @@ -239,7 +239,7 @@ type EitherUpgrade = future::Either, OutboundUpg /// An upgrade on an authenticated, non-multiplexed [`Transport`]. /// -/// See [`Builder::upgrade`](Builder::upgrade). +/// See [`Transport::upgrade`] #[derive(Debug, Copy, Clone)] pub struct Upgrade { inner: T, upgrade: U } diff --git a/misc/multiaddr/src/lib.rs b/misc/multiaddr/src/lib.rs index 56b46743..f81b8ada 100644 --- a/misc/multiaddr/src/lib.rs +++ b/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>::new(Arc::make_mut(&mut self.bytes)); w.set_position(w.get_ref().len() as u64); diff --git a/misc/multistream-select/src/length_delimited.rs b/misc/multistream-select/src/length_delimited.rs index bc363c7e..3efd700e 100644 --- a/misc/multistream-select/src/length_delimited.rs +++ b/misc/multistream-select/src/length_delimited.rs @@ -284,10 +284,10 @@ impl LengthDelimitedReader { /// # 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() } diff --git a/misc/multistream-select/src/negotiated.rs b/misc/multistream-select/src/negotiated.rs index 7611aee5..ff50d3c7 100644 --- a/misc/multistream-select/src/negotiated.rs +++ b/misc/multistream-select/src/negotiated.rs @@ -62,7 +62,7 @@ impl Future for NegotiatedComplete { } impl Negotiated { - /// 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 } } diff --git a/misc/multistream-select/src/protocol.rs b/misc/multistream-select/src/protocol.rs index d895a227..55e2943a 100644 --- a/misc/multistream-select/src/protocol.rs +++ b/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 MessageIO { /// /// 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 MessageReader { /// /// 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() diff --git a/misc/rw-stream-sink/src/lib.rs b/misc/rw-stream-sink/src/lib.rs index 9268e299..0eb2feb0 100644 --- a/misc/rw-stream-sink/src/lib.rs +++ b/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}}; diff --git a/muxers/yamux/src/lib.rs b/muxers/yamux/src/lib.rs index bc8db663..785c3ac7 100644 --- a/muxers/yamux/src/lib.rs +++ b/muxers/yamux/src/lib.rs @@ -37,7 +37,7 @@ impl fmt::Debug for Yamux { } struct Inner { - /// 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 Stream for LocalIncoming { } impl Unpin for LocalIncoming { -} \ No newline at end of file +} diff --git a/protocols/gossipsub/src/behaviour.rs b/protocols/gossipsub/src/behaviour.rs index a60257fc..a0f3e3db 100644 --- a/protocols/gossipsub/src/behaviour.rs +++ b/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); diff --git a/protocols/kad/src/behaviour.rs b/protocols/kad/src/behaviour.rs index e7e117c8..51bbe581 100644 --- a/protocols/kad/src/behaviour.rs +++ b/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`]. diff --git a/protocols/kad/src/jobs.rs b/protocols/kad/src/jobs.rs index 9f5f8c67..f7a2cd4d 100644 --- a/protocols/kad/src/jobs.rs +++ b/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. diff --git a/protocols/kad/src/kbucket.rs b/protocols/kad/src/kbucket.rs index 735ced57..0f985759 100644 --- a/protocols/kad/src/kbucket.rs +++ b/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) } diff --git a/protocols/kad/src/protocol.rs b/protocols/kad/src/protocol.rs index e24301e4..e79243b3 100644 --- a/protocols/kad/src/protocol.rs +++ b/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; diff --git a/protocols/kad/src/query/peers.rs b/protocols/kad/src/query/peers.rs index 97ad0166..049ffe58 100644 --- a/protocols/kad/src/query/peers.rs +++ b/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; diff --git a/protocols/noise/src/lib.rs b/protocols/noise/src/lib.rs index e5a54d20..1730160f 100644 --- a/protocols/noise/src/lib.rs +++ b/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 { diff --git a/protocols/ping/src/handler.rs b/protocols/ping/src/handler.rs index d552fe36..a2ab5316 100644 --- a/protocols/ping/src/handler.rs +++ b/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; diff --git a/protocols/ping/src/lib.rs b/protocols/ping/src/lib.rs index 197c8f26..024d6b0b 100644 --- a/protocols/ping/src/lib.rs +++ 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; diff --git a/protocols/secio/src/lib.rs b/protocols/secio/src/lib.rs index 8ff85f50..8c067f6b 100644 --- a/protocols/secio/src/lib.rs +++ b/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() { diff --git a/swarm/src/behaviour.rs b/swarm/src/behaviour.rs index 504482c6..250020bd 100644 --- a/swarm/src/behaviour.rs +++ b/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>; - /// Iterator returned by [`listened_addresses`]. + /// Iterator returned by [`listened_addresses`](PollParameters::listened_addresses). type ListenedAddressesIter: ExactSizeIterator; - /// Iterator returned by [`external_addresses`]. + /// Iterator returned by [`external_addresses`](PollParameters::external_addresses). type ExternalAddressesIter: ExactSizeIterator; /// Returns the list of protocol the behaviour supports when a remote negotiates a protocol on @@ -190,6 +190,8 @@ pub trait NetworkBehaviourEventProcess { /// 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 { /// Instructs the `Swarm` to return an event when it is being polled. diff --git a/swarm/src/protocols_handler.rs b/swarm/src/protocols_handler.rs index 1e66dfe1..b689cd9d 100644 --- a/swarm/src/protocols_handler.rs +++ b/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