protocols/: Add documentation on peer discovery (#2465)

Co-authored-by: Max Inden <[email protected]>

Author: Frederik-Baetens

protocols/gossipsub/src/lib.rs

@@ -51,6 +51,18 @@
 //! integers. They are chosen at random in this implementation of gossipsub, but are sequential in
 //! the current go implementation.
 //!
+//! # Peer Discovery
+//!
+//! Gossipsub does not provide peer discovery by itself. Peer discovery is the process by which
+//! peers in a p2p network exchange information about each other among other reasons to become resistant
+//! against the failure or replacement of the
+//! [boot nodes](https://docs.libp2p.io/reference/glossary/#boot-node) of the network.
+//!
+//! Peer
+//! discovery can e.g. be implemented with the help of the [Kademlia](https://github.com/libp2p/specs/blob/master/kad-dht/README.md) protocol
+//! in combination with the [Identify](https://github.com/libp2p/specs/tree/master/identify) protocol. See the
+//! Kademlia implementation documentation for more information.
+//!
 //! # Using Gossipsub
 //!
 //! ## GossipsubConfig

protocols/identify/src/lib.rs

@@ -26,6 +26,13 @@
 //! At least one identification request is sent on a newly established
 //! connection, beyond which the behaviour does not keep connections alive.
 //!
+//! # Important Discrepancies
+//!
+//! - **Using Identify with other protocols** Unlike some other libp2p implementations,
+//! rust-libp2p does not treat Identify as a core protocol. This means that other protocols cannot
+//! rely upon the existence of Identify, and need to be manually hooked up to Identify in order to
+//! make use of its capabilities.
+//!
 //! # Usage
 //!
 //! The [`Identify`] struct implements a `NetworkBehaviour` that negotiates

protocols/kad/src/lib.rs

@@ -19,6 +19,21 @@
 // DEALINGS IN THE SOFTWARE.
 
 //! Implementation of the libp2p-specific Kademlia protocol.
+//!
+//! See [specification](https://github.com/libp2p/specs/blob/master/kad-dht/README.md) for details.
+//!
+//! # Important Discrepancies
+//!
+//! - **Peer Discovery with Identify** In other libp2p implementations, the
+//! [Identify](https://github.com/libp2p/specs/tree/master/identify) protocol might be seen as a core protocol. Rust-libp2p
+//! tries to stay as generic as possible, and does not make this assumption.
+//! This means that the Identify protocol must be manually hooked up to Kademlia through calls
+//! 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,
+//! 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.
 
 // TODO: we allow dead_code for now because this library contains a lot of unused code that will
 //       be useful later for record store