From 07e30ae923cf7defb7a3f42143424094195f2f2b Mon Sep 17 00:00:00 2001
From: Martin Chaine <chaine.martin@gmail.com>
Date: Tue, 28 Aug 2018 23:13:06 +0200
Subject: [PATCH] net: rework tokio_tcp and tokio_udp re-exports (#548)

This patch keeps the primary net types in `tokio::net` and moves
secondary types to a protocol specific submodules.

Primary types are the ones that users are most likely to name (`TcpStream`,
`TcpListener`, `UdpSocket`, ...)

Secondary types are the operation futures.
---
 src/net.rs | 99 +++++++++++++++++++++++++++++++++++-------------------
 1 file changed, 65 insertions(+), 34 deletions(-)

diff --git a/src/net.rs b/src/net.rs
index 6cf00f3e7..79810b6a7 100644
--- a/src/net.rs
+++ b/src/net.rs
@@ -1,54 +1,85 @@
-//! TCP/UDP bindings for `tokio`.
+//! TCP/UDP/Unix bindings for `tokio`.
 //!
-//! This module contains the TCP/UDP networking types, similar to the standard
+//! This module contains the TCP/UDP/Unix networking types, similar to the standard
 //! library, which can be used to implement networking protocols.
 //!
-//! # TCP
+//! # Organization
 //!
-//! Connecting to an address, via TCP, can be done using [`TcpStream`]'s
-//! [`connect`] method, which returns [`ConnectFuture`]. `ConnectFuture`
-//! implements a future which returns a `TcpStream`.
+//! * [`TcpListener`] and [`TcpStream`] provide functionality for communication over TCP
+//! * [`UdpSocket`] and [`UdpFramed`] provide functionality for communication over UDP
+//! * [`UnixListener`] and [`UnixStream`] provide functionality for communication over a
+//! Unix Domain Socket **(available on Unix only)**
 //!
-//! To listen on an address [`TcpListener`] can be used. `TcpListener`'s
-//! [`incoming`][incoming_method] method can be used to accept new connections.
-//! It return the [`Incoming`] struct, which implements a stream which returns
-//! `TcpStream`s.
-//!
-//! [`TcpStream`]: struct.TcpStream.html
-//! [`connect`]: struct.TcpStream.html#method.connect
-//! [`ConnectFuture`]: struct.ConnectFuture.html
 //! [`TcpListener`]: struct.TcpListener.html
-//! [incoming_method]: struct.TcpListener.html#method.incoming
-//! [`Incoming`]: struct.Incoming.html
-//!
-//! # UDP
-//!
-//! The main struct for UDP is the [`UdpSocket`], which represents a UDP socket.
-//! Reading and writing to it can be done using futures, which return the
-//! [`RecvDgram`] and [`SendDgram`] structs respectively.
-//!
-//! For convenience it's also possible to convert raw datagrams into higher-level
-//! frames.
-//!
+//! [`TcpStream`]: struct.TcpStream.html
 //! [`UdpSocket`]: struct.UdpSocket.html
-//! [`RecvDgram`]: struct.RecvDgram.html
-//! [`SendDgram`]: struct.SendDgram.html
 //! [`UdpFramed`]: struct.UdpFramed.html
-//! [`framed`]: struct.UdpSocket.html#method.framed
+//! [`UnixListener`]: struct.UnixListener.html
+//! [`UnixStream`]: struct.UnixStream.html
 
-pub use tokio_tcp::{TcpStream, ConnectFuture};
-pub use tokio_tcp::{TcpListener, Incoming};
-pub use tokio_udp::{UdpSocket, UdpFramed, SendDgram, RecvDgram};
+pub mod tcp {
+    //! TCP bindings for `tokio`.
+    //!
+    //! Connecting to an address, via TCP, can be done using [`TcpStream`]'s
+    //! [`connect`] method, which returns [`ConnectFuture`]. `ConnectFuture`
+    //! implements a future which returns a `TcpStream`.
+    //!
+    //! To listen on an address [`TcpListener`] can be used. `TcpListener`'s
+    //! [`incoming`][incoming_method] method can be used to accept new connections.
+    //! It return the [`Incoming`] struct, which implements a stream which returns
+    //! `TcpStream`s.
+    //!
+    //! [`TcpStream`]: struct.TcpStream.html
+    //! [`connect`]: struct.TcpStream.html#method.connect
+    //! [`ConnectFuture`]: struct.ConnectFuture.html
+    //! [`TcpListener`]: struct.TcpListener.html
+    //! [incoming_method]: struct.TcpListener.html#method.incoming
+    //! [`Incoming`]: struct.Incoming.html
+    pub use tokio_tcp::{ConnectFuture, Incoming, TcpListener, TcpStream};
+}
+pub use self::tcp::{TcpListener, TcpStream};
+
+#[deprecated(note = "use `tokio::net::tcp::ConnectFuture` instead")]
+#[doc(hidden)]
+pub type ConnectFuture = self::tcp::ConnectFuture;
+#[deprecated(note = "use `tokio::net::tcp::Incoming` instead")]
+#[doc(hidden)]
+pub type Incoming = self::tcp::Incoming;
+
+pub mod udp {
+    //! UDP bindings for `tokio`.
+    //!
+    //! The main struct for UDP is the [`UdpSocket`], which represents a UDP socket.
+    //! Reading and writing to it can be done using futures, which return the
+    //! [`RecvDgram`] and [`SendDgram`] structs respectively.
+    //!
+    //! For convenience it's also possible to convert raw datagrams into higher-level
+    //! frames.
+    //!
+    //! [`UdpSocket`]: struct.UdpSocket.html
+    //! [`RecvDgram`]: struct.RecvDgram.html
+    //! [`SendDgram`]: struct.SendDgram.html
+    //! [`UdpFramed`]: struct.UdpFramed.html
+    //! [`framed`]: struct.UdpSocket.html#method.framed
+    pub use tokio_udp::{RecvDgram, SendDgram, UdpFramed, UdpSocket};
+}
+pub use self::udp::{UdpFramed, UdpSocket};
+
+#[deprecated(note = "use `tokio::net::udp::RecvDgram` instead")]
+#[doc(hidden)]
+pub type RecvDgram<T> = self::udp::RecvDgram<T>;
+#[deprecated(note = "use `tokio::net::udp::SendDgram` instead")]
+#[doc(hidden)]
+pub type SendDgram<T> = self::udp::SendDgram<T>;
 
 #[cfg(unix)]
 pub mod unix {
-    //! Unix domain socket bindings for `tokio`.
+    //! Unix domain socket bindings for `tokio` (only available on unix systems).
 
     pub use tokio_uds::{
         ConnectFuture, Incoming, RecvDgram, SendDgram, UCred, UnixDatagram, UnixListener,
         UnixStream,
     };
 }
-
 #[cfg(unix)]
 pub use self::unix::{UnixListener, UnixStream};