From 2dfdc1c4821c097066f93f64d49abe035616c9dc Mon Sep 17 00:00:00 2001
From: Yoshua Wuyts <yoshuawuyts@gmail.com>
Date: Tue, 12 Nov 2019 23:07:39 +0100
Subject: [PATCH] polish lib.rs examples

Signed-off-by: Yoshua Wuyts <yoshuawuyts@gmail.com>
---
 src/lib.rs           | 50 ++++++++++++++++++++++++++++++++++++++------
 src/task/block_on.rs |  8 ++++---
 2 files changed, 49 insertions(+), 9 deletions(-)

diff --git a/src/lib.rs b/src/lib.rs
index ddc6462..5442909 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -131,17 +131,55 @@
 //!
 //! # Examples
 //!
-//! Spawn a task and block the current thread on its result:
+//! All examples require the [`"attributes"` feature](#features) to be enabled.
+//! This feature is not enabled by default because it significantly impacts
+//! compile times. See [`task::block_on`] for an alternative way to start
+//! executing tasks.
 //!
+//! Call an async function from the main function:
+//!
+//! ```
+//! async fn say_hello() {
+//!     println!("Hello, world!");
+//! }
+//!
+//! #[async_std::main]
+//! async fn main() {
+//!     say_hello().await;
+//! }
+//! ```
+//!
+//! Await two futures concurrently, and return a tuple of their output:
+//!
+//! ```
+//! #[async_std::main]
+//! async fn main() {
+//!     let a = || async move { 1u8 };
+//!     let b = || async move { 2u8 };
+//!     assert_eq!(a.join(b).await, (1u8, 2u8))
+//! }
 //! ```
-//! use async_std::task;
 //!
-//! fn main() {
-//!     task::block_on(async {
-//!         println!("Hello, world!");
-//!     })
+//! Create a UDP server that echoes back each received message to the sender:
+//!
+//! ```no_run
+//! use async_std::net::UdpSocket;
+//!
+//! #[async_std::main]
+//! async fn main() -> std::io::Result<()> {
+//!     let mut socket = UdpSocket::bind("127.0.0.1:8080")?;
+//!     println!("Listening on {}", socket.local_addr()?);
+//!
+//!     let mut buf = vec![0u8; 1024];
+//!
+//!     loop {
+//!         let (recv, peer) = socket.recv_from(&mut buf).await?;
+//!         let sent = socket.send_to(&buf[..recv], &peer).await?;
+//!         println!("Sent {} out of {} bytes to {}", sent, recv, peer);
+//!     }
 //! }
 //! ```
+//! [`task::block_on`]: task/fn.block_on.html
 //!
 //! # Features
 //!
diff --git a/src/task/block_on.rs b/src/task/block_on.rs
index f61a22b..80259c5 100644
--- a/src/task/block_on.rs
+++ b/src/task/block_on.rs
@@ -28,9 +28,11 @@ use crate::task::{Context, Poll, Task, Waker};
 /// ```no_run
 /// use async_std::task;
 ///
-/// task::block_on(async {
-///     println!("Hello, world!");
-/// })
+/// fn main() {
+///     task::block_on(async {
+///         println!("Hello, world!");
+///     })
+/// }
 /// ```
 pub fn block_on<F, T>(future: F) -> T
 where