*: Link to libp2p/specs in doc comments (#3077)

core/src/peer_id.rs

@@ -35,6 +35,7 @@ const MAX_INLINE_KEY_LENGTH: usize = 42;
 /// Identifier of a peer of the network.
 ///
 /// The data is a multihash of the public key of the peer.
+/// See the [spec](https://github.com/libp2p/specs/blob/master/peer-ids/peer-ids.md) for more information.
 #[derive(Clone, Copy, Eq, Hash, Ord, PartialEq, PartialOrd)]
 pub struct PeerId {
     multihash: Multihash,

muxers/mplex/src/lib.rs

@@ -18,6 +18,8 @@
 // FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
 // DEALINGS IN THE SOFTWARE.
 
+//! Implementation of the Stream Multiplexer [Mplex](https://github.com/libp2p/specs/blob/master/mplex/README.md) protocol.
+
 #![cfg_attr(docsrs, feature(doc_cfg, doc_auto_cfg))]
 
 mod codec;

muxers/yamux/src/lib.rs

@@ -18,8 +18,7 @@
 // FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
 // DEALINGS IN THE SOFTWARE.
 
-//! Implements the Yamux multiplexing protocol for libp2p, see also the
+//! Implementation of the [Yamux](https://github.com/hashicorp/yamux/blob/master/spec.md)  multiplexing protocol for libp2p.
-//! [specification](https://github.com/hashicorp/yamux/blob/master/spec.md).
 
 #![cfg_attr(docsrs, feature(doc_cfg, doc_auto_cfg))]
 

protocols/autonat/src/lib.rs

@@ -18,7 +18,7 @@
 // FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
 // DEALINGS IN THE SOFTWARE.
 
-//! Implementation of the AutoNAT protocol.
+//! Implementation of the [AutoNAT](https://github.com/libp2p/specs/blob/master/autonat/README.md) protocol.
 
 #![cfg_attr(docsrs, feature(doc_cfg, doc_auto_cfg))]
 

protocols/floodsub/src/lib.rs

@@ -18,8 +18,7 @@
 // FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
 // DEALINGS IN THE SOFTWARE.
 
-//! Implements the floodsub protocol, see also the:
+//! Implementation of the [floodsub](https://github.com/libp2p/specs/blob/master/pubsub/README.md) protocol.
-//! [spec](https://github.com/libp2p/specs/tree/master/pubsub).
 
 #![cfg_attr(docsrs, feature(doc_cfg, doc_auto_cfg))]
 

protocols/gossipsub/src/lib.rs

@@ -18,6 +18,8 @@
 // FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
 // DEALINGS IN THE SOFTWARE.
 
+//! Implementation of the [Gossipsub](https://github.com/libp2p/specs/blob/master/pubsub/gossipsub/README.md) protocol.
+//!
 //! Gossipsub is a P2P pubsub (publish/subscription) routing layer designed to extend upon
 //! floodsub and meshsub routing protocols.
 //!

protocols/kad/src/lib.rs

@@ -18,9 +18,7 @@
 // FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
 // DEALINGS IN THE SOFTWARE.
 
-//! Implementation of the libp2p-specific Kademlia protocol.
+//! Implementation of the libp2p-specific [Kademlia](https://github.com/libp2p/specs/blob/master/kad-dht/README.md) protocol.
-//!
-//! See [specification](https://github.com/libp2p/specs/blob/master/kad-dht/README.md) for details.
 //!
 //! # Important Discrepancies
 //!
@@ -31,7 +29,7 @@
 //! to [`Kademlia::add_address`].
 //! If you choose not to use the Identify protocol, and do not provide an alternative peer
 //! discovery mechanism, a Kademlia node will not discover nodes beyond the network's
-//! [boot nodes](https://docs.libp2p.io/reference/glossary/#boot-node). Without the Identify protocol,
+//! [boot nodes](https://docs.libp2p.io/concepts/glossary/#boot-node). Without the Identify protocol,
 //! existing nodes in the kademlia network cannot obtain the listen addresses
 //! of nodes querying them, and thus will not be able to add them to their routing table.
 

protocols/mdns/src/lib.rs

@@ -18,6 +18,8 @@
 // FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
 // DEALINGS IN THE SOFTWARE.
 
+//! Implementation of the libp2p-specific [mDNS](https://github.com/libp2p/specs/blob/master/discovery/mdns.md) protocol.
+//!
 //! mDNS is a protocol defined by [RFC 6762](https://tools.ietf.org/html/rfc6762) that allows
 //! querying nodes that correspond to a certain domain name.
 //!

protocols/relay/src/lib.rs

@@ -19,7 +19,7 @@
 // FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
 // DEALINGS IN THE SOFTWARE.
 
-//! libp2p circuit relay implementations
+//! Implementation of libp2p [circuit relay](https://github.com/libp2p/specs/blob/master/relay/README.md) protocol.
 
 #![cfg_attr(docsrs, feature(doc_cfg, doc_auto_cfg))]
 

protocols/relay/src/v2.rs

@@ -19,7 +19,7 @@
 // DEALINGS IN THE SOFTWARE.
 
 //! Implementation of the [libp2p circuit relay v2
-//! specification](https://github.com/libp2p/specs/issues/314).
+//! specification](https://github.com/libp2p/specs/blob/master/relay/circuit-v2.md).
 
 #[allow(clippy::derive_partial_eq_without_eq)]
 mod message_proto {

protocols/rendezvous/src/lib.rs

@@ -18,6 +18,8 @@
 // FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
 // DEALINGS IN THE SOFTWARE.
 
+//! Implementation of the [Rendezvous](https://github.com/libp2p/specs/blob/master/rendezvous/README.md) protocol.
+
 #![cfg_attr(docsrs, feature(doc_cfg, doc_auto_cfg))]
 
 pub use self::codec::{Cookie, ErrorCode, Namespace, NamespaceTooLong, Registration, Ttl};

src/tutorials.rs

@@ -1,2 +1,24 @@
+// Copyright 2018 Parity Technologies (UK) Ltd.
+//
+// Permission is hereby granted, free of charge, to any person obtaining a
+// copy of this software and associated documentation files (the "Software"),
+// to deal in the Software without restriction, including without limitation
+// the rights to use, copy, modify, merge, publish, distribute, sublicense,
+// and/or sell copies of the Software, and to permit persons to whom the
+// Software is furnished to do so, subject to the following conditions:
+//
+// The above copyright notice and this permission notice shall be included in
+// all copies or substantial portions of the Software.
+//
+// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
+// OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+// FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+// DEALINGS IN THE SOFTWARE.
+
+//! Rust-libp2p Tutorials to get started with.
+
 pub mod hole_punching;
 pub mod ping;

transports/dns/src/lib.rs

@@ -18,7 +18,8 @@
 // FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
 // DEALINGS IN THE SOFTWARE.
 
-//! # libp2p-dns
+//! # [DNS name resolution](https://github.com/libp2p/specs/blob/master/addressing/README.md#ip-and-name-resolution)
+//! [`Transport`] for libp2p.
 //!
 //! This crate provides the type [`GenDnsConfig`] with its instantiations
 //! [`DnsConfig`] and `TokioDnsConfig` for use with `async-std` and `tokio`,

transports/plaintext/src/lib.rs

@@ -18,6 +18,8 @@
 // FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
 // DEALINGS IN THE SOFTWARE.
 
+//! Implementation of the [plaintext](https://github.com/libp2p/specs/blob/master/plaintext/README.md) protocol.
+
 #![cfg_attr(docsrs, feature(doc_cfg, doc_auto_cfg))]
 
 use crate::error::PlainTextError;

transports/pnet/src/lib.rs

@@ -18,9 +18,9 @@
 // FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
 // DEALINGS IN THE SOFTWARE.
 
-//! The `pnet` protocol implements *Pre-shared Key Based Private Networks in libp2p*,
+//! Implementation of the [pnet](https://github.com/libp2p/specs/blob/master/pnet/Private-Networks-PSK-V1.md) protocol.
-//! as specified in [the spec](https://github.com/libp2p/specs/blob/master/pnet/Private-Networks-PSK-V1.md)
 //!
+//| The `pnet` protocol implements *Pre-shared Key Based Private Networks in libp2p*.
 //! Libp2p nodes configured with a pre-shared key can only communicate with other nodes with
 //! the same key.