From 4ddc4371709562d2bd1d0373f0555f7c31926e53 Mon Sep 17 00:00:00 2001 From: Carl Lerche Date: Mon, 25 Nov 2019 14:32:55 -0800 Subject: doc: add more doc_cfg annotations (#1821) Also makes the `tokio::net::{tcp, udp, unix}` modules only for "utility" types. The primary types are in `tokio::net` directly. --- tokio/src/lib.rs | 4 +-- tokio/src/macros/cfg.rs | 55 +++++++++++++++++++++++++++++++------- tokio/src/net/addr.rs | 8 ++++++ tokio/src/net/mod.rs | 9 ++++--- tokio/src/net/tcp/listener.rs | 46 ++++++++++++++++---------------- tokio/src/net/tcp/mod.rs | 25 ++++-------------- tokio/src/net/tcp/stream.rs | 60 ++++++++++++++++++++++-------------------- tokio/src/net/udp/mod.rs | 13 +++------ tokio/src/net/udp/socket.rs | 8 +++--- tokio/src/net/unix/datagram.rs | 8 +++--- tokio/src/net/unix/listener.rs | 8 +++--- tokio/src/net/unix/mod.rs | 15 +++++------ tokio/src/net/unix/stream.rs | 16 ++++++----- tokio/src/sync/watch.rs | 9 ++++--- tokio/tests/uds_datagram.rs | 2 +- tokio/tests/uds_stream.rs | 2 +- 16 files changed, 162 insertions(+), 126 deletions(-) diff --git a/tokio/src/lib.rs b/tokio/src/lib.rs index cd7a62ea..967d82a6 100644 --- a/tokio/src/lib.rs +++ b/tokio/src/lib.rs @@ -72,8 +72,8 @@ //! * Functions for [running blocking operations][blocking] in an asynchronous //! task context. //! -//! The `tokio::task` module is present only when the "rt-core" feature flag is -//! enabled. +//! The [`tokio::task`] module is present only when the "rt-core" feature flag +//! is enabled. //! //! [tasks]: task/index.html#what-are-tasks //! [`tokio::task`]: crate::task diff --git a/tokio/src/macros/cfg.rs b/tokio/src/macros/cfg.rs index 1e660d8f..959eed22 100644 --- a/tokio/src/macros/cfg.rs +++ b/tokio/src/macros/cfg.rs @@ -161,6 +161,7 @@ macro_rules! cfg_signal { ($($item:item)*) => { $( #[cfg(feature = "signal")] + #[cfg_attr(docsrs, doc(cfg(feature = "signal")))] #[cfg(not(loom))] $item )* @@ -169,13 +170,21 @@ macro_rules! cfg_signal { macro_rules! cfg_stream { ($($item:item)*) => { - $( #[cfg(feature = "stream")] $item )* + $( + #[cfg(feature = "stream")] + #[cfg_attr(docsrs, doc(cfg(feature = "stream")))] + $item + )* } } macro_rules! cfg_sync { ($($item:item)*) => { - $( #[cfg(feature = "sync")] $item )* + $( + #[cfg(feature = "sync")] + #[cfg_attr(docsrs, doc(cfg(feature = "sync")))] + $item + )* } } @@ -187,7 +196,11 @@ macro_rules! cfg_not_sync { macro_rules! cfg_rt_core { ($($item:item)*) => { - $( #[cfg(feature = "rt-core")] $item )* + $( + #[cfg(feature = "rt-core")] + #[cfg_attr(docsrs, doc(cfg(feature = "rt-core")))] + $item + )* } } @@ -199,7 +212,11 @@ macro_rules! cfg_not_rt_core { macro_rules! cfg_rt_threaded { ($($item:item)*) => { - $( #[cfg(feature = "rt-threaded")] $item )* + $( + #[cfg(feature = "rt-threaded")] + #[cfg_attr(docsrs, doc(cfg(feature = "rt-threaded")))] + $item + )* } } @@ -211,13 +228,21 @@ macro_rules! cfg_not_rt_threaded { macro_rules! cfg_tcp { ($($item:item)*) => { - $( #[cfg(feature = "tcp")] $item )* + $( + #[cfg(feature = "tcp")] + #[cfg_attr(docsrs, doc(cfg(feature = "tcp")))] + $item + )* } } macro_rules! cfg_test_util { ($($item:item)*) => { - $( #[cfg(feature = "test-util")] $item )* + $( + #[cfg(feature = "test-util")] + #[cfg_attr(docsrs, doc(cfg(feature = "test-util")))] + $item + )* } } @@ -229,7 +254,11 @@ macro_rules! cfg_not_test_util { macro_rules! cfg_time { ($($item:item)*) => { - $( #[cfg(feature = "time")] $item )* + $( + #[cfg(feature = "time")] + #[cfg_attr(docsrs, doc(cfg(feature = "time")))] + $item + )* } } @@ -241,12 +270,20 @@ macro_rules! cfg_not_time { macro_rules! cfg_udp { ($($item:item)*) => { - $( #[cfg(feature = "udp")] $item )* + $( + #[cfg(feature = "udp")] + #[cfg_attr(docsrs, doc(cfg(feature = "udp")))] + $item + )* } } macro_rules! cfg_uds { ($($item:item)*) => { - $( #[cfg(all(unix, feature = "uds"))] $item )* + $( + #[cfg(all(unix, feature = "uds"))] + #[cfg_attr(docsrs, doc(cfg(feature = "uds")))] + $item + )* } } diff --git a/tokio/src/net/addr.rs b/tokio/src/net/addr.rs index aa66c5fa..8e3bf434 100644 --- a/tokio/src/net/addr.rs +++ b/tokio/src/net/addr.rs @@ -5,6 +5,14 @@ use std::net::{IpAddr, Ipv4Addr, Ipv6Addr, SocketAddr, SocketAddrV4, SocketAddrV /// Convert or resolve without blocking to one or more `SocketAddr` values. /// +/// # DNS +/// +/// Implementations of `ToSocketAddrs` for string types require a DNS lookup. +/// These implementations are only provided when Tokio is used with the +/// **`dns`** feature flag. +/// +/// # Calling +/// /// Currently, this trait is only used as an argument to Tokio functions that /// need to reference a target socket address. /// diff --git a/tokio/src/net/mod.rs b/tokio/src/net/mod.rs index ac913b21..a7b98cdb 100644 --- a/tokio/src/net/mod.rs +++ b/tokio/src/net/mod.rs @@ -28,15 +28,18 @@ pub use addr::ToSocketAddrs; cfg_tcp! { pub mod tcp; - pub use tcp::{TcpListener, TcpStream}; + pub use tcp::listener::TcpListener; + pub use tcp::stream::TcpStream; } cfg_udp! { pub mod udp; - pub use udp::UdpSocket; + pub use udp::socket::UdpSocket; } cfg_uds! { pub mod unix; - pub use unix::{UnixDatagram, UnixListener, UnixStream}; + pub use unix::datagram::UnixDatagram; + pub use unix::listener::UnixListener; + pub use unix::stream::UnixStream; } diff --git a/tokio/src/net/tcp/listener.rs b/tokio/src/net/tcp/listener.rs index 5db5ee80..59762b13 100644 --- a/tokio/src/net/tcp/listener.rs +++ b/tokio/src/net/tcp/listener.rs @@ -9,28 +9,30 @@ use std::io; use std::net::{self, SocketAddr}; use std::task::{Context, Poll}; -/// An I/O object representing a TCP socket listening for incoming connections. -/// -/// # Examples -/// -/// ```no_run -/// use tokio::net::TcpListener; -/// -/// use std::io; -/// # async fn process_socket(_socket: T) {} -/// -/// #[tokio::main] -/// async fn main() -> io::Result<()> { -/// let mut listener = TcpListener::bind("127.0.0.1:8080").await?; -/// -/// loop { -/// let (socket, _) = listener.accept().await?; -/// process_socket(socket).await; -/// } -/// } -/// ``` -pub struct TcpListener { - io: PollEvented, +cfg_tcp! { + /// A TCP socket server, listening for connections. + /// + /// # Examples + /// + /// ```no_run + /// use tokio::net::TcpListener; + /// + /// use std::io; + /// # async fn process_socket(_socket: T) {} + /// + /// #[tokio::main] + /// async fn main() -> io::Result<()> { + /// let mut listener = TcpListener::bind("127.0.0.1:8080").await?; + /// + /// loop { + /// let (socket, _) = listener.accept().await?; + /// process_socket(socket).await; + /// } + /// } + /// ``` + pub struct TcpListener { + io: PollEvented, + } } impl TcpListener { diff --git a/tokio/src/net/tcp/mod.rs b/tokio/src/net/tcp/mod.rs index 929a1e00..d5354b38 100644 --- a/tokio/src/net/tcp/mod.rs +++ b/tokio/src/net/tcp/mod.rs @@ -1,22 +1,7 @@ -//! TCP bindings for `tokio`. -//! -//! This module contains the TCP networking types, similar to the standard -//! library, which can be used to implement networking protocols. -//! -//! Connecting to an address, via TCP, can be done using [`TcpStream`]'s -//! [`connect`] method, which returns a future which returns a `TcpStream`. -//! -//! To listen on an address [`TcpListener`] can be used. `TcpListener`'s -//! [`incoming`][TcpListener::incoming] 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 -//! [`TcpListener`]: struct.TcpListener.html +//! TCP utility types -mod listener; -pub use listener::TcpListener; +pub(crate) mod listener; +pub(crate) use listener::TcpListener; mod incoming; pub use incoming::Incoming; @@ -24,5 +9,5 @@ pub use incoming::Incoming; mod split; pub use split::{ReadHalf, WriteHalf}; -mod stream; -pub use stream::TcpStream; +pub(crate) mod stream; +pub(crate) use stream::TcpStream; diff --git a/tokio/src/net/tcp/stream.rs b/tokio/src/net/tcp/stream.rs index 34d3a493..b961e363 100644 --- a/tokio/src/net/tcp/stream.rs +++ b/tokio/src/net/tcp/stream.rs @@ -12,35 +12,37 @@ use std::pin::Pin; use std::task::{Context, Poll}; use std::time::Duration; -/// An I/O object representing a TCP stream connected to a remote endpoint. -/// -/// A TCP stream can either be created by connecting to an endpoint, via the -/// [`connect`] method, or by [accepting] a connection from a [listener]. -/// -/// [`connect`]: struct.TcpStream.html#method.connect -/// [accepting]: struct.TcpListener.html#method.accept -/// [listener]: struct.TcpListener.html -/// -/// # Examples -/// -/// ```no_run -/// use tokio::net::TcpStream; -/// use tokio::prelude::*; -/// use std::error::Error; -/// -/// #[tokio::main] -/// async fn main() -> Result<(), Box> { -/// // Connect to a peer -/// let mut stream = TcpStream::connect("127.0.0.1:8080").await?; -/// -/// // Write some data. -/// stream.write_all(b"hello world!").await?; -/// -/// Ok(()) -/// } -/// ``` -pub struct TcpStream { - io: PollEvented, +cfg_tcp! { + /// A TCP stream between a local and a remote socket. + /// + /// A TCP stream can either be created by connecting to an endpoint, via the + /// [`connect`] method, or by [accepting] a connection from a [listener]. + /// + /// [`connect`]: struct.TcpStream.html#method.connect + /// [accepting]: struct.TcpListener.html#method.accept + /// [listener]: struct.TcpListener.html + /// + /// # Examples + /// + /// ```no_run + /// use tokio::net::TcpStream; + /// use tokio::prelude::*; + /// use std::error::Error; + /// + /// #[tokio::main] + /// async fn main() -> Result<(), Box> { + /// // Connect to a peer + /// let mut stream = TcpStream::connect("127.0.0.1:8080").await?; + /// + /// // Write some data. + /// stream.write_all(b"hello world!").await?; + /// + /// Ok(()) + /// } + /// ``` + pub struct TcpStream { + io: PollEvented, + } } impl TcpStream { diff --git a/tokio/src/net/udp/mod.rs b/tokio/src/net/udp/mod.rs index b4d3ea46..a616f4d5 100644 --- a/tokio/src/net/udp/mod.rs +++ b/tokio/src/net/udp/mod.rs @@ -1,14 +1,7 @@ -//! UDP bindings for `tokio`. -//! -//! This module contains the UDP networking types, similar to the standard -//! library, which can be used to implement networking protocols. -//! -//! The main struct for UDP is the [`UdpSocket`], which represents a UDP socket. -//! -//! [`UdpSocket`]: struct.UdpSocket +//! UDP utility types. -mod socket; -pub use socket::UdpSocket; +pub(crate) mod socket; +pub(crate) use socket::UdpSocket; mod split; pub use split::{RecvHalf, SendHalf, ReuniteError}; diff --git a/tokio/src/net/udp/socket.rs b/tokio/src/net/udp/socket.rs index 30cc104e..c22ebd92 100644 --- a/tokio/src/net/udp/socket.rs +++ b/tokio/src/net/udp/socket.rs @@ -9,9 +9,11 @@ use std::io; use std::net::{self, Ipv4Addr, Ipv6Addr, SocketAddr}; use std::task::{Context, Poll}; -/// An I/O object representing a UDP socket. -pub struct UdpSocket { - io: PollEvented, +cfg_udp! { + /// A UDP socket + pub struct UdpSocket { + io: PollEvented, + } } impl UdpSocket { diff --git a/tokio/src/net/unix/datagram.rs b/tokio/src/net/unix/datagram.rs index eb8bfe4c..ae1372f6 100644 --- a/tokio/src/net/unix/datagram.rs +++ b/tokio/src/net/unix/datagram.rs @@ -10,9 +10,11 @@ use std::os::unix::net::{self, SocketAddr}; use std::path::Path; use std::task::{Context, Poll}; -/// An I/O object representing a Unix datagram socket. -pub struct UnixDatagram { - io: PollEvented, +cfg_uds! { + /// An I/O object representing a Unix datagram socket. + pub struct UnixDatagram { + io: PollEvented, + } } impl UnixDatagram { diff --git a/tokio/src/net/unix/listener.rs b/tokio/src/net/unix/listener.rs index 7791b05f..5f4787ec 100644 --- a/tokio/src/net/unix/listener.rs +++ b/tokio/src/net/unix/listener.rs @@ -12,9 +12,11 @@ use std::os::unix::net::{self, SocketAddr}; use std::path::Path; use std::task::{Context, Poll}; -/// A Unix socket which can accept connections from other Unix sockets. -pub struct UnixListener { - io: PollEvented, +cfg_uds! { + /// A Unix socket which can accept connections from other Unix sockets. + pub struct UnixListener { + io: PollEvented, + } } impl UnixListener { diff --git a/tokio/src/net/unix/mod.rs b/tokio/src/net/unix/mod.rs index 1ec6fa8e..ddba60d1 100644 --- a/tokio/src/net/unix/mod.rs +++ b/tokio/src/net/unix/mod.rs @@ -1,21 +1,18 @@ -//! Unix Domain Sockets for Tokio. -//! -//! This crate provides APIs for using Unix Domain Sockets with Tokio. +//! Unix domain socket utility types -mod datagram; -pub use datagram::UnixDatagram; +pub(crate) mod datagram; mod incoming; pub use incoming::Incoming; -mod listener; -pub use listener::UnixListener; +pub(crate) mod listener; +pub(crate) use listener::UnixListener; mod split; pub use split::{ReadHalf, WriteHalf}; -mod stream; -pub use stream::UnixStream; +pub(crate) mod stream; +pub(crate) use stream::UnixStream; mod ucred; pub use ucred::UCred; diff --git a/tokio/src/net/unix/stream.rs b/tokio/src/net/unix/stream.rs index a430fa17..5151b08a 100644 --- a/tokio/src/net/unix/stream.rs +++ b/tokio/src/net/unix/stream.rs @@ -14,13 +14,15 @@ use std::path::Path; use std::pin::Pin; use std::task::{Context, Poll}; -/// A structure representing a connected Unix socket. -/// -/// This socket can be connected directly with `UnixStream::connect` or accepted -/// from a listener with `UnixListener::incoming`. Additionally, a pair of -/// anonymous Unix sockets can be created with `UnixStream::pair`. -pub struct UnixStream { - io: PollEvented, +cfg_uds! { + /// A structure representing a connected Unix socket. + /// + /// This socket can be connected directly with `UnixStream::connect` or accepted + /// from a listener with `UnixListener::incoming`. Additionally, a pair of + /// anonymous Unix sockets can be created with `UnixStream::pair`. + pub struct UnixStream { + io: PollEvented, + } } impl UnixStream { diff --git a/tokio/src/sync/watch.rs b/tokio/src/sync/watch.rs index 36bab7bc..124027f9 100644 --- a/tokio/src/sync/watch.rs +++ b/tokio/src/sync/watch.rs @@ -45,10 +45,11 @@ //! threads and can be used in a concurrent environment. Clones of [`Receiver`] //! handles may be moved to separate threads and also used concurrently. //! -//! [`Sender`]: struct.Sender.html -//! [`Receiver`]: struct.Receiver.html -//! [`channel`]: fn.channel.html -//! [`Sender::closed`]: struct.Sender.html#method.closed +//! [`Sender`]: crate::sync::watch::Sender +//! [`Receiver`]: crate::sync::watch::Receiver +//! [`Receiver::recv`]: crate::sync::watch::Receiver::recv +//! [`channel`]: crate::sync::watch::channel +//! [`Sender::closed`]: crate::sync::watch::Sender::closed use crate::future::poll_fn; use crate::sync::task::AtomicWaker; diff --git a/tokio/tests/uds_datagram.rs b/tokio/tests/uds_datagram.rs index 504ede52..dd995237 100644 --- a/tokio/tests/uds_datagram.rs +++ b/tokio/tests/uds_datagram.rs @@ -2,7 +2,7 @@ #![cfg(feature = "full")] #![cfg(unix)] -use tokio::net::unix::*; +use tokio::net::UnixDatagram; use std::io; diff --git a/tokio/tests/uds_stream.rs b/tokio/tests/uds_stream.rs index 33279590..15760e22 100644 --- a/tokio/tests/uds_stream.rs +++ b/tokio/tests/uds_stream.rs @@ -3,7 +3,7 @@ #![cfg(unix)] use tokio::io::{AsyncReadExt, AsyncWriteExt}; -use tokio::net::unix::*; +use tokio::net::{UnixListener, UnixStream}; use futures::future::try_join; -- cgit v1.2.3