Add some crate-level documentation to network-libp2p (#2483)

substrate/core/network-libp2p/src/lib.rs

@@ -16,7 +16,89 @@
 
 //! Networking layer of Substrate.
 //!
-//! **Important**: This crate is unstable and the API and usage may change.
+//! # Overview
+//!
+//! This crate handles the following network mechanisms:
+//!
+//! - Discovering nodes that are part of the network.
+//! - Connecting to said nodes and accepting incoming connections.
+//! - Encrypting communications between nodes.
+//! - Ensure that nodes are really the `PeerId` that they pretend to be.
+//! - Ensuring that the nodes belong to the same chain as us before reporting a new connection.
+//!
+//! From the point of view of our node, each other node on the network has a reputation value in
+//! the form of an `i32`. We try to establish connections towards nodes with a higher reputation
+//! over nodes with a lower reputation.
+//!
+//! Establishing connections to other nodes is automatically performed by this crate, and there is
+//! no way to influence this, except by adjusting reputations.
+//!
+//! ## About the term "connecting"
+//!
+//! The documentation of this crate uses the words "connected" and "disconnected". It is important
+//! to note that this doesn't correspond to actual TCP/IP connections and disconnections. Libp2p
+//! will maintain connections that aren't reported by the API of this crate, and TCP/IP connections
+//! can be kept alive even after we have reported a disconnect in order to potentially reuse them.
+//!
+//! # Usage
+//!
+//! > **Important**: This crate is unstable and the API and usage may change.
+//!
+//! The first step is to crate a [`RegisteredProtocol`] describing the protocol, and a
+//! [`NetworkConfiguration`] describing the network. Then call [`start_service`] with them, which
+//! returns a [`Service`] object and a [`substrate_peerset::PeersetHandle`].
+//!
+//! The former allows you to know what happens on the network and to send messages, while the
+//! latter can be used to adjust the reputations of nodes.
+//!
+//! You must call the `poll` method of [`Service`] in order to make the network progress and in
+//! order to update the internal state of the [`Service`]. Calling `poll` will produce
+//! [`ServiceEvent`]s, which inform you of what happened on the network.
+//!
+//! Please keep in mind that the state of the [`Service`] only updates itself in a way
+//! corresponding to the [`ServiceEvent`] that `poll` returns.
+//! 
+//! Illustration:
+//! 
+//! - You call [`Service::connected_peers`] to get the list of nodes we are connected to.
+//! - If you then call [`Service::connected_peers`] again, the returned list will always be the
+//!   same, no matter what happened on the wire.
+//! - If you then call [`Service::poll`] and a [`ServiceEvent::OpenedCustomProtocol`] event is
+//!   returned, then the concerned node, and only the concerned node, will be added to the list of
+//!   nodes we are connected to.
+//! - Similarly, if [`Service::poll`] produces a [`ServiceEvent::ClosedCustomProtocol`] event, then
+//!   only the concerned node will disappear from the list.
+//! - And if [`Service::poll`] returns neither [`ServiceEvent::OpenedCustomProtocol`] nor
+//!   [`ServiceEvent::ClosedCustomProtocol`], then the list of connected nodes doesn't change.
+//!
+//! ## Example
+//!
+//! ```no_run
+//! # use futures::prelude::*;
+//! use substrate_network_libp2p::ServiceEvent;
+//!
+//! let proto = substrate_network_libp2p::RegisteredProtocol::new(&b"hello"[..], &[0]);
+//! let config = substrate_network_libp2p::NetworkConfiguration::default();
+//! let (mut service, _peerset) = substrate_network_libp2p::start_service(config, proto).unwrap();
+//!
+//! tokio::run(futures::future::poll_fn(move || {
+//! 	loop {
+//! 		match service.poll().unwrap() {
+//! 			Async::NotReady => return Ok(Async::NotReady),
+//! 			Async::Ready(Some(ServiceEvent::OpenedCustomProtocol { peer_id, .. })) => {
+//! 				println!("now connected to {:?}", peer_id);
+//! 				service.send_custom_message(&peer_id, b"hello world!".to_vec());
+//! 			}
+//! 			Async::Ready(Some(ServiceEvent::ClosedCustomProtocol { peer_id, .. })) =>
+//! 				println!("now disconnected from {:?}", peer_id),
+//! 			Async::Ready(Some(ServiceEvent::CustomMessage { peer_id, message })) =>
+//! 				println!("received message from {:?}: {:?}", peer_id, message),
+//! 			Async::Ready(None) => return Ok(Async::Ready(())),
+//! 			_ => {}
+//! 		}
+//! 	}
+//! }));
+//! ```
 //!
 
 mod behaviour;