Add documentation to the core (#820)

core/src/lib.rs

@@ -52,6 +52,14 @@
 //!   how to handle incoming substreams, which protocols are supported, when to open a new
 //!   outbound substream, etc. See the `protocols_handler` trait.
 //!
+//! # High-level APIs vs low-level APIs
+//!
+//! This crate provides two sets of APIs:
+//!
+//! - The low-level APIs are contained within the `nodes` module. See the documentation for more
+//!   information.
+//! - The high-level APIs include the concepts of `Swarm`, `ProtocolsHandler`, `NetworkBehaviour`
+//!   and `Topology`.
 
 
 /// Multi-address re-export.

core/src/nodes/listeners.rs

@@ -18,6 +18,8 @@
 // FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
 // DEALINGS IN THE SOFTWARE.
 
+//! Manage listening on multiple multiaddresses at once.
+
 use futures::prelude::*;
 use std::fmt;
 use void::Void;

core/src/nodes/mod.rs

@@ -18,6 +18,14 @@
 // FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
 // DEALINGS IN THE SOFTWARE.
 
+//! Low-level networking primitives.
+//!
+//! Contains structs that are aiming at providing very precise control over what happens over the
+//! network.
+//!
+//! The more complete and highest-level struct is the `RawSwarm`. The `RawSwarm` directly or
+//! indirectly uses all the other structs of this module.
+
 pub mod collection;
 pub mod handled_node;
 pub mod handled_node_tasks;

core/src/protocols_handler/mod.rs

@@ -18,6 +18,21 @@
 // FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
 // DEALINGS IN THE SOFTWARE.
 
+//! Once we are connected to a node, a *protocols handler* handles one or more specific protocols
+//! on this connection.
+//!
+//! This includes: how to handle incoming substreams, which protocols are supported, when to open
+//! a new outbound substream, and so on.
+//!
+//! Each implementation of the `ProtocolsHandler` trait handles one or more specific protocols.
+//! Two `ProtocolsHandler`s can be combined together with the `select()` method in order to build
+//! a `ProtocolsHandler` that combines both. This can be repeated multiple times in order to create
+//! a handler that handles all the protocols that you wish.
+//!
+//! > **Note**: A `ProtocolsHandler` handles one or more protocols in relation to a specific
+//! >           connection with a remote. In order to handle a protocol that requires knowledge of
+//! >           the network as a whole, see the `NetworkBehaviour` trait.
+
 use crate::upgrade::{
     InboundUpgrade,
     OutboundUpgrade,
@@ -49,14 +64,15 @@ mod select;
 /// Communication with a remote over a set of protocols opened in two different ways:
 ///
 /// - Dialing, which is a voluntary process. In order to do so, make `poll()` return an
-///   `OutboundSubstreamRequest` variant containing the connection upgrade to use to start using a protocol.
+///   `OutboundSubstreamRequest` variant containing the connection upgrade to use to start using a
+///   protocol.
 /// - Listening, which is used to determine which protocols are supported when the remote wants
 ///   to open a substream. The `listen_protocol()` method should return the upgrades supported when
 ///   listening.
 ///
 /// The upgrade when dialing and the upgrade when listening have to be of the same type, but you
-/// are free to return for example an `OrUpgrade` enum, or an enum of your own, containing the upgrade
-/// you want depending on the situation.
+/// are free to return for example an `OrUpgrade` enum, or an enum of your own, containing the
+/// upgrade you want depending on the situation.
 ///
 /// # Shutting down
 ///
@@ -72,19 +88,6 @@ mod select;
 /// might already be closed or unresponsive. They should therefore not rely on being able to
 /// deliver messages.
 ///
-/// # Relationship with `NodeHandler`.
-///
-/// This trait is very similar to the `NodeHandler` trait. The fundamental differences are:
-///
-/// - The `NodeHandler` trait gives you more control and is therefore more difficult to implement.
-/// - The `NodeHandler` trait is designed to have exclusive ownership of the connection to a
-///   node, while the `ProtocolsHandler` trait is designed to handle only a specific set of
-///   protocols. Two or more implementations of `ProtocolsHandler` can be combined into one that
-///   supports all the protocols together, which is not possible with `NodeHandler`.
-///
-// TODO: add a "blocks connection closing" system, so that we can gracefully close a connection
-//       when it's no longer needed, and so that for example the periodic pinging system does not
-//       keep the connection alive forever
 pub trait ProtocolsHandler {
     /// Custom event that can be received from the outside.
     type InEvent;

core/src/swarm.rs

@@ -18,6 +18,29 @@
 // FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
 // DEALINGS IN THE SOFTWARE.
 
+//! High level manager of the network.
+//!
+//! The `Swarm` struct contains the state of the network as a whole. The entire behaviour of a
+//! libp2p network can be controlled through the `Swarm`.
+//!
+//! # Initializing a Swarm
+//!
+//! Creating a `Swarm` requires three things:
+//! 
+//! - An implementation of the `Transport` trait. This is the type that will be used in order to
+//!   reach nodes on the network based on their address. See the `transport` module for more
+//!   information.
+//! - An implementation of the `NetworkBehaviour` trait. This is a state machine that defines how
+//!   the swarm should behave once it is connected to a node.
+//! - An implementation of the `Topology` trait. This is a container that holds the list of nodes
+//!   that we think are part of the network. See the `topology` module for more information.
+//!
+//! # Network behaviour
+//!
+//! The `NetworkBehaviour` trait is implemented on types that indicate to the swarm how it should
+//! behave. This includes which protocols are supported and which nodes to try to connect to.
+//!
+
 use crate::{
     Transport, Multiaddr, PublicKey, PeerId, InboundUpgrade, OutboundUpgrade, UpgradeInfo, ProtocolName,
     muxing::StreamMuxer,
@@ -347,7 +370,7 @@ pub trait NetworkBehaviourEventProcess<TEvent> {
     fn inject_event(&mut self, event: TEvent);
 }
 
-/// Parameters passed to `poll()` that the `NetworkBehaviour` has access to.
+/// Parameters passed to `poll()`, that the `NetworkBehaviour` has access to.
 // TODO: #[derive(Debug)]
 pub struct PollParameters<'a, TTopology: 'a> {
     topology: &'a mut TTopology,

core/src/topology/mod.rs

@@ -18,6 +18,19 @@
 // FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
 // DEALINGS IN THE SOFTWARE.
 
+//! A *network topology* is a collection of nodes that are part of the network or that we think
+//! are part of the network. In other words, it is essentially a container whose layout is
+//! optimized for certain operations.
+//!
+//! In libp2p, a *topology* is any struct that implements at least the `Topology` trait. In order
+//! to build a `Swarm`, you have to give to it ownership of a type that implements this trait.
+//!
+//! In order to use some protocols defined outside of `libp2p-core` (such as Kademlia) in your
+//! `Swarm`, you will have to implement additional traits on your topology.
+//!
+//! While the `MemoryTopology` is provided as a ready-to-go topology that is suitable for quick
+//! prototyping, it shouldn't be used in an actual high-performance production software.
+
 use std::collections::HashMap;
 use crate::{Multiaddr, PeerId, PublicKey};
 

core/src/transport/mod.rs

@@ -20,14 +20,11 @@
 
 //! Handles entering a connection with a peer.
 //!
-//! The two main elements of this module are the `Transport` and `ConnectionUpgrade` traits.
-//! `Transport` is implemented on objects that allow dialing and listening. `ConnectionUpgrade` is
-//! implemented on objects that make it possible to upgrade a connection (for example by adding an
-//! encryption middleware to the connection).
+//! The main element of this module is the `Transport` trait. It is implemented on objects that
+//! allow dialing and listening.
 //!
-//! Thanks to the `Transport::or_transport`, `Transport::with_upgrade` and
-//! `UpgradedNode::or_upgrade` methods, you can combine multiple transports and/or upgrades
-//! together in a complex chain of protocols negotiation.
+//! The rest of the module holds combinators that allow tweaking an implementation of `Transport`,
+//! combine multiple transports together, or combine a transport with an upgrade.
 
 use crate::{InboundUpgrade, OutboundUpgrade, nodes::raw_swarm::ConnectedPoint};
 use futures::prelude::*;