fix docs (#204)

Author: divagant-martian

src/lib.rs

@@ -1,57 +1,52 @@
-#![warn(rust_2018_idioms)]
 #![deny(rustdoc::broken_intra_doc_links)]
-#![cfg_attr(docsrs, feature(doc_cfg))]
-#![allow(clippy::needless_doctest_main)]
 //! An implementation of [Discovery V5](https://github.com/ethereum/devp2p/blob/master/discv5/discv5.md).
 //!
 //! # Overview
 //!
-//! Discovery v5 is a protocol designed for encrypted peer discovery and topic advertisement. Each peer/node
-//! on the network is identified via it's ENR ([Ethereum Name
+//! Discovery v5 is a protocol designed for encrypted peer discovery and topic advertisement. Each
+//! peer/node on the network is identified via it's ENR ([Ethereum Name
 //! Record](https://eips.ethereum.org/EIPS/eip-778)), which is essentially a signed key-value store
 //! containing the node's public key and optionally IP address and port.
 //!
-//! Discv5 employs a kademlia-like routing table to store and manage discovered peers (and topics tba). The
-//! protocol allows for external IP discovery in NAT environments through regular PING/PONG's with
+//! Discv5 employs a kademlia-like routing table to store and manage discovered peers. The protocol
+//! allows for external IP discovery in NAT environments through regular PING/PONG's with
 //! discovered nodes. Nodes return the external IP address that they have received and a simple
 //! majority is chosen as our external IP address. If an external IP address is updated, this is
-//! produced as an event to notify the swarm (if one is used for this behaviour).
+//! produced as an event.
 //!
-//!  For a simple CLI discovery service see [discv5-cli](https://github.com/AgeManning/discv5-cli)
+//! For a simple CLI discovery service see [discv5-cli](https://github.com/AgeManning/discv5-cli)
 //!
-//! This protocol is split into four main sections/layers:
+//! This protocol is split into four main layers:
 //!
-//!  * Socket - The [`socket`] module is responsible for opening the underlying UDP socket. It
-//!  creates individual tasks for sending/encoding and receiving/decoding packets from the UDP
-//!  socket.
-//!  * Handler - The protocol's communication is encrypted with `AES_GCM`. All node communication
-//!  undergoes a handshake, which results in a [`Session`]. [`Session`]'s are established when
-//!  needed and get dropped after a timeout. This section manages the creation and maintenance of
-//!  sessions between nodes and the encryption/decryption of packets from the socket. It is
-//!  realised by the [`handler::Handler`] struct and it runs in its own task.
-//!  * Service - This section contains the protocol-level logic. In particular it manages the
-//!  routing table of known ENR's, (and topic registration/advertisement tba) and performs
-//!  parallel queries for peer discovery. This section is realised by the [`Service`] struct. This
-//!  also runs in it's own thread.
-//!  * Application - This section is the user-facing API which can start/stop the underlying
-//!  tasks, initiate queries and obtain metrics about the underlying server.
+//! - [`socket`]: Responsible for opening the underlying UDP socket. It creates individual tasks
+//! for sending/encoding and receiving/decoding packets from the UDP socket.
+//! - [`handler`]: The protocol's communication is encrypted with `AES_GCM`. All node communication
+//! undergoes a handshake, which results in a `Session`. These are established when needed and get
+//! dropped after a timeout. The creation and maintenance of sessions between nodes and the
+//! encryption/decryption of packets from the socket is realised by the [`handler::Handler`] struct
+//! runnning in its own task.
+//! - [`service`]: Contains the protocol-level logic. The [`service::Service`] manages the routing
+//! table of known ENR's, and performs parallel queries for peer discovery. It also runs in it's
+//! own task.
+//! - [`Discv5`]: The application level. Manages the user-facing API. It starts/stops the underlying
+//! tasks, allows initiating queries and obtain metrics about the underlying server.
 //!
-//!  ## Event Stream
+//! ## Event Stream
 //!
-//!  The [`Discv5`] struct provides access to an event-stream which allows the user to listen to
-//!  [`Discv5Event`] that get generated from the underlying server. The stream can be obtained
-//!  from the [`Discv5::event_stream()`] function.
+//! The [`Discv5`] struct provides access to an event-stream which allows the user to listen to
+//! [`Discv5Event`] that get generated from the underlying server. The stream can be obtained from
+//! the [`Discv5::event_stream`] function.
 //!
-//!  ## Runtimes
+//! ## Runtimes
 //!
-//!  Discv5 requires a tokio runtime with timing and io enabled. An explicit runtime can be given
-//!  via the configuration. See the [`Discv5ConfigBuilder`] for further details. Such a runtime
-//!  must implement the [`Executor`] trait.
+//! Discv5 requires a tokio runtime with timing and io enabled. An explicit runtime can be given
+//! via the configuration. See the [`Discv5ConfigBuilder`] for further details. Such a runtime must
+//! implement the [`Executor`] trait.
 //!
-//!  If an explicit runtime is not provided via the configuration parameters, it is assumed that
-//!  a tokio runtime is present when creating the [`Discv5`] struct. The struct will use the
-//!  existing runtime for spawning the underlying server tasks. If a runtime is not present, the
-//!  creation of the [`Discv5`] struct will panic.
+//! If an explicit runtime is not provided via the configuration parameters, it is assumed that a
+//! tokio runtime is present when creating the [`Discv5`] struct. The struct will use the existing
+//! runtime for spawning the underlying server tasks. If a runtime is not present, the creation of
+//! the [`Discv5`] struct will panic.
 //!
 //! # Usage
 //!
@@ -98,14 +93,6 @@
 //!       println!("Found nodes: {:?}", found_nodes);
 //!    });
 //! ```
-//!
-//! [`Discv5`]: struct.Discv5.html
-//! [`Discv5Event`]: enum.Discv5Event.html
-//! [`Discv5Config`]: config/struct.Discv5Config.html
-//! [`Discv5ConfigBuilder`]: config/struct.Discv5ConfigBuilder.html
-//! [Packet]: packet/enum.Packet.html
-//! [`Service`]: service/struct.Service.html
-//! [`Session`]: session/struct.Session.html
 
 mod config;
 mod discv5;