Merge pull request #396 from async-rs/net-docs

standardize net docs

src/net/mod.rs

@@ -1,14 +1,42 @@
 //! Networking primitives for TCP/UDP communication.
 //!
-//! For OS-specific networking primitives like Unix domain sockets, refer to the [`async_std::os`]
-//! module.
+//! This module provides networking functionality for the Transmission Control and User
+//! Datagram Protocols, as well as types for IP and socket addresses.
 //!
 //! This module is an async version of [`std::net`].
 //!
+//! # Organization
+//!
+//! * [`TcpListener`] and [`TcpStream`] provide functionality for communication over TCP
+//! * [`UdpSocket`] provides functionality for communication over UDP
+//! * [`IpAddr`] represents IP addresses of either IPv4 or IPv6; [`Ipv4Addr`] and
+//!   [`Ipv6Addr`] are respectively IPv4 and IPv6 addresses
+//! * [`SocketAddr`] represents socket addresses of either IPv4 or IPv6; [`SocketAddrV4`]
+//!   and [`SocketAddrV6`] are respectively IPv4 and IPv6 socket addresses
+//! * [`ToSocketAddrs`] is a trait that used for generic address resolution when interacting
+//!   with networking objects like [`TcpListener`], [`TcpStream`] or [`UdpSocket`]
+//! * Other types are return or parameter types for various methods in this module
+//!
+//! [`IpAddr`]: enum.IpAddr.html
+//! [`Ipv4Addr`]: struct.Ipv4Addr.html
+//! [`Ipv6Addr`]: struct.Ipv6Addr.html
+//! [`SocketAddr`]: enum.SocketAddr.html
+//! [`SocketAddrV4`]: struct.SocketAddrV4.html
+//! [`SocketAddrV6`]: struct.SocketAddrV6.html
+//! [`TcpListener`]: struct.TcpListener.html
+//! [`TcpStream`]: struct.TcpStream.html
+//! [`ToSocketAddrs`]: trait.ToSocketAddrs.html
+//! [`UdpSocket`]: struct.UdpSocket.html
+//!
+//! # Platform-specific extensions
+//!
+//! APIs such as Unix domain sockets are available on certain platforms only. You can find
+//! platform-specific extensions in the [`async_std::os`] module.
+//!
 //! [`async_std::os`]: ../os/index.html
 //! [`std::net`]: https://doc.rust-lang.org/std/net/index.html
 //!
-//! ## Examples
+//! # Examples
 //!
 //! A simple UDP echo server:
 //!