Do not redefine modules in futures crate (rust-lang#2299)

futures-channel/src/lib.rs

@@ -1,9 +1,14 @@
 //! Asynchronous channels.
 //!
-//! This crate provides channels that can be used to communicate between
-//! asynchronous tasks.
+//! Like threads, concurrent tasks sometimes need to communicate with each
+//! other. This module contains two basic abstractions for doing so:
 //!
-//! All items of this library are only available when the `std` or `alloc` feature of this
+//! - [oneshot], a way of sending a single value from one task to another.
+//! - [mpsc], a multi-producer, single-consumer channel for sending values
+//!   between tasks, analogous to the similarly-named structure in the standard
+//!   library.
+//!
+//! All items are only available when the `std` or `alloc` feature of this
 //! library is activated, and it is activated by default.
 
 #![cfg_attr(feature = "cfg-target-has-atomic", feature(cfg_target_has_atomic))]

futures-executor/src/lib.rs

@@ -1,7 +1,40 @@
 //! Built-in executors and related tools.
 //!
-//! All items of this library are only available when the `std` feature of this
+//! All asynchronous computation occurs within an executor, which is
+//! capable of spawning futures as tasks. This module provides several
+//! built-in executors, as well as tools for building your own.
+//!
+//! All items are only available when the `std` feature of this
 //! library is activated, and it is activated by default.
+//!
+//! # Using a thread pool (M:N task scheduling)
+//!
+//! Most of the time tasks should be executed on a [thread pool](ThreadPool).
+//! A small set of worker threads can handle a very large set of spawned tasks
+//! (which are much lighter weight than threads). Tasks spawned onto the pool
+//! with the [`spawn_ok`](ThreadPool::spawn_ok) function will run ambiently on
+//! the created threads.
+//!
+//! # Spawning additional tasks
+//!
+//! Tasks can be spawned onto a spawner by calling its [`spawn_obj`] method
+//! directly. In the case of `!Send` futures, [`spawn_local_obj`] can be used
+//! instead.
+//!
+//! # Single-threaded execution
+//!
+//! In addition to thread pools, it's possible to run a task (and the tasks
+//! it spawns) entirely within a single thread via the [`LocalPool`] executor.
+//! Aside from cutting down on synchronization costs, this executor also makes
+//! it possible to spawn non-`Send` tasks, via [`spawn_local_obj`]. The
+//! [`LocalPool`] is best suited for running I/O-bound tasks that do relatively
+//! little work between I/O operations.
+//!
+//! There is also a convenience function [`block_on`] for simply running a
+//! future to completion on the current thread.
+//!
+//! [`spawn_obj`]: https://docs.rs/futures/0.3/futures/task/trait.Spawn.html#tymethod.spawn_obj
+//! [`spawn_local_obj`]: https://docs.rs/futures/0.3/futures/task/trait.LocalSpawn.html#tymethod.spawn_local_obj
 
 #![cfg_attr(not(feature = "std"), no_std)]
 #![warn(missing_docs, missing_debug_implementations, rust_2018_idioms, unreachable_pub)]

futures-util/src/compat/mod.rs

@@ -1,4 +1,4 @@
-//! Futures 0.1 / 0.3 shims
+//! Interop between `futures` 0.1 and 0.3.
 //!
 //! This module is only available when the `compat` feature of this
 //! library is activated.

futures-util/src/future/mod.rs

@@ -1,8 +1,13 @@
-//! Futures
+//! Asynchronous values.
 //!
-//! This module contains a number of functions for working with `Future`s,
-//! including the [`FutureExt`] trait and the [`TryFutureExt`] trait which add
-//! methods to `Future` types.
+//! This module contains:
+//!
+//! - The [`Future`] trait.
+//! - The [`FutureExt`] and [`TryFutureExt`] trait, which provides adapters for
+//!   chaining and composing futures.
+//! - Top-level future combinators like [`lazy`](lazy()) which creates a future
+//!   from a closure that defines its return value, and [`ready`](ready()),
+//!   which constructs a future with an immediate defined value.
 
 #[cfg(feature = "alloc")]
 pub use futures_core::future::{BoxFuture, LocalBoxFuture};

futures-util/src/io/mod.rs

@@ -1,12 +1,19 @@
-//! IO
+//! Asynchronous I/O.
 //!
-//! This module contains a number of functions for working with
-//! `AsyncRead`, `AsyncWrite`, `AsyncSeek`, and `AsyncBufRead` types, including
-//! the `AsyncReadExt`, `AsyncWriteExt`, `AsyncSeekExt`, and `AsyncBufReadExt`
-//! traits which add methods to the `AsyncRead`, `AsyncWrite`, `AsyncSeek`,
-//! and `AsyncBufRead` types.
+//! This module is the asynchronous version of `std::io`. It defines four
+//! traits, [`AsyncRead`], [`AsyncWrite`], [`AsyncSeek`], and [`AsyncBufRead`],
+//! which mirror the `Read`, `Write`, `Seek`, and `BufRead` traits of the
+//! standard library. However, these traits integrate with the asynchronous
+//! task system, so that if an I/O object isn't ready for reading (or writing),
+//! the thread is not blocked, and instead the current task is queued to be
+//! woken when I/O is ready.
 //!
-//! This module is only available when the `io` and `std` features of this
+//! In addition, the [`AsyncReadExt`], [`AsyncWriteExt`], [`AsyncSeekExt`], and
+//! [`AsyncBufReadExt`] extension traits offer a variety of useful combinators
+//! for operating with asynchronous I/O objects, including ways to work with
+//! them using futures, streams and sinks.
+//!
+//! This module is only available when the `std` feature of this
 //! library is activated, and it is activated by default.
 
 #[cfg(feature = "io-compat")]

futures-util/src/lib.rs

@@ -334,10 +334,8 @@ pub mod io;
 #[doc(hidden)]
 pub use crate::io::{AsyncBufReadExt, AsyncReadExt, AsyncSeekExt, AsyncWriteExt};
 
+#[cfg(feature = "alloc")]
+pub mod lock;
+
 mod fns;
 mod unfold_state;
-
-cfg_target_has_atomic! {
-    #[cfg(feature = "alloc")]
-    pub mod lock;
-}

futures-util/src/lock/mod.rs

@@ -3,18 +3,20 @@
 //! This module is only available when the `std` or `alloc` feature of this
 //! library is activated, and it is activated by default.
 
-#[cfg(feature = "std")]
-mod mutex;
-#[cfg(feature = "std")]
-pub use self::mutex::{MappedMutexGuard, Mutex, MutexLockFuture, MutexGuard};
+cfg_target_has_atomic! {
+    #[cfg(feature = "std")]
+    mod mutex;
+    #[cfg(feature = "std")]
+    pub use self::mutex::{MappedMutexGuard, Mutex, MutexLockFuture, MutexGuard};
 
-#[cfg(any(feature = "bilock", feature = "sink", feature = "io"))]
-#[cfg_attr(docsrs, doc(cfg(feature = "bilock")))]
-#[cfg_attr(not(feature = "bilock"), allow(unreachable_pub))]
-mod bilock;
-#[cfg(feature = "bilock")]
-#[cfg_attr(docsrs, doc(cfg(feature = "bilock")))]
-pub use self::bilock::{BiLock, BiLockAcquire, BiLockGuard, ReuniteError};
-#[cfg(any(feature = "sink", feature = "io"))]
-#[cfg(not(feature = "bilock"))]
-pub(crate) use self::bilock::BiLock;
+    #[cfg(any(feature = "bilock", feature = "sink", feature = "io"))]
+    #[cfg_attr(docsrs, doc(cfg(feature = "bilock")))]
+    #[cfg_attr(not(feature = "bilock"), allow(unreachable_pub))]
+    mod bilock;
+    #[cfg(feature = "bilock")]
+    #[cfg_attr(docsrs, doc(cfg(feature = "bilock")))]
+    pub use self::bilock::{BiLock, BiLockAcquire, BiLockGuard, ReuniteError};
+    #[cfg(any(feature = "sink", feature = "io"))]
+    #[cfg(not(feature = "bilock"))]
+    pub(crate) use self::bilock::BiLock;
+}

futures-util/src/never.rs

@@ -1,5 +1,6 @@
-//! Definition of the `Never` type,
-//! a stand-in for the `!` type until it becomes stable.
+//! This module contains the `Never` type.
+//!
+//! Values of this type can never be created and will never exist.
 
 /// A type with no possible values.
 ///

futures-util/src/sink/mod.rs

@@ -1,10 +1,10 @@
-//! Sinks
+//! Asynchronous sinks.
 //!
-//! This module contains a number of functions for working with `Sink`s,
-//! including the `SinkExt` trait which adds methods to `Sink` types.
+//! This module contains:
 //!
-//! This module is only available when the `sink` feature of this
-//! library is activated, and it is activated by default.
+//! - The [`Sink`] trait, which allows you to asynchronously write data.
+//! - The [`SinkExt`] trait, which provides adapters for chaining and composing
+//!   sinks.
 
 use crate::future::Either;
 use core::pin::Pin;

futures-util/src/stream/mod.rs

@@ -1,8 +1,13 @@
-//! Streams
+//! Asynchronous streams.
 //!
-//! This module contains a number of functions for working with `Stream`s,
-//! including the [`StreamExt`] trait and the [`TryStreamExt`] trait which add
-//! methods to `Stream` types
+//! This module contains:
+//!
+//! - The [`Stream`] trait, for objects that can asynchronously produce a
+//!   sequence of values.
+//! - The [`StreamExt`] and [`TryStreamExt`] trait, which provides adapters for
+//!   chaining and composing streams.
+//! - Top-level stream constructors like [`iter`](iter()) which creates a
+//!   stream from an iterator.
 
 #[cfg(feature = "alloc")]
 pub use futures_core::stream::{BoxStream, LocalBoxStream};

futures-util/src/task/mod.rs

@@ -1,4 +1,22 @@
-//! Task notification
+//! Tools for working with tasks.
+//!
+//! This module contains:
+//!
+//! - [`Spawn`], a trait for spawning new tasks.
+//! - [`Context`], a context of an asynchronous task,
+//!   including a handle for waking up the task.
+//! - [`Waker`], a handle for waking up a task.
+//!
+//! The remaining types and traits in the module are used for implementing
+//! executors or dealing with synchronization issues around task wakeup.
+
+pub use futures_core::task::{Context, Poll, RawWaker, RawWakerVTable, Waker};
+
+pub use futures_task::{FutureObj, LocalFutureObj, LocalSpawn, Spawn, SpawnError, UnsafeFutureObj};
+
+pub use futures_task::noop_waker;
+#[cfg(feature = "std")]
+pub use futures_task::noop_waker_ref;
 
 cfg_target_has_atomic! {
     #[cfg(feature = "alloc")]
@@ -15,11 +33,3 @@ cfg_target_has_atomic! {
 
 mod spawn;
 pub use self::spawn::{LocalSpawnExt, SpawnExt};
-
-pub use futures_core::task::{Context, Poll, RawWaker, RawWakerVTable, Waker};
-
-pub use futures_task::{FutureObj, LocalFutureObj, LocalSpawn, Spawn, SpawnError, UnsafeFutureObj};
-
-pub use futures_task::noop_waker;
-#[cfg(feature = "std")]
-pub use futures_task::noop_waker_ref;