test: Improve tokio_test::task docs
#5132
Conversation
| @@ -11,7 +36,7 @@ use std::task::{Context, Poll, RawWaker, RawWakerVTable, Waker}; | |||
|
|
|||
| use tokio_stream::Stream; | |||
|
|
|||
| /// TODO: dox | |||
| /// Spawn a future into a [`Spawn`] which wraps the future in a mocked executor. | |||
There was a problem hiding this comment.
recommend also adding an example here
There was a problem hiding this comment.
I would add more "so what" / why docs here. maybe something like:
As a side note, I'd probably make another function for streams and bound the generic—I get that they are functionally the same but it's not at all obvious you can pass a stream in here & calling spawn on a stream doesn't really make sense.
/// Test utility to spawn the [`Future`] or [`Stream`] into a [`Spawn`] container
///
/// The `Spawn` container enables direct polling and introspection of the state of the future which is often required
/// when testing code that implements [`Future`] or [`Stream`]. The [`Spawn`] container enables you to poll the
/// future directly without requiring you to construct your own `Context` or `Waker`. It also handles the bookkeeping required to track wakeups & future state.
There was a problem hiding this comment.
I was keeping the example at the mod docs so ill just point to that.
| @@ -11,7 +36,7 @@ use std::task::{Context, Poll, RawWaker, RawWakerVTable, Waker}; | |||
|
|
|||
| use tokio_stream::Stream; | |||
|
|
|||
| /// TODO: dox | |||
| /// Spawn a future into a [`Spawn`] which wraps the future in a mocked executor. | |||
There was a problem hiding this comment.
I would add more "so what" / why docs here. maybe something like:
As a side note, I'd probably make another function for streams and bound the generic—I get that they are functionally the same but it's not at all obvious you can pass a stream in here & calling spawn on a stream doesn't really make sense.
/// Test utility to spawn the [`Future`] or [`Stream`] into a [`Spawn`] container
///
/// The `Spawn` container enables direct polling and introspection of the state of the future which is often required
/// when testing code that implements [`Future`] or [`Stream`]. The [`Spawn`] container enables you to poll the
/// future directly without requiring you to construct your own `Context` or `Waker`. It also handles the bookkeeping required to track wakeups & future state.
| /// | ||
| /// This can be used to spawn a [`Future`] or a [`Stream`]. | ||
| /// | ||
| /// For more information, check the module docs. |
| /// Future spawned on a mock task that can be used to poll the future or stream | ||
| /// without needing pinning or context types. |
| /// If `T` is a [`Future`] then poll it. This will handle pinning and the context | ||
| /// type for the future. |
There was a problem hiding this comment.
a little misleading—kinda makes me think that the code would be
if t.is_future() { poll } else { do nothing }
There was a problem hiding this comment.
yeah though not sure how to describe that its a type system if statement rather than a rust language one...
Darksonn
added
T-docs
cc @rcoh