Improve documentation

.rustfmt.toml

@@ -3,4 +3,5 @@ use_field_init_shorthand = true
 use_try_shorthand = true
 use_small_heuristics = "Max"
 newline_style = "auto"
-edition = "2021"
+edition = "2021"
+format_code_in_doc_comments = true

Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "worst-executor"
-version = "0.1.0"
+version = "0.1.1"
 edition = "2021"
 license = "MIT/Apache-2.0"
 authors = ["Elichai Turkel <[email protected]>"]

README.md

@@ -1,5 +1,5 @@
 # Worst Executor
-[![Build status](https://github.com/elichai/worst-executor/workflows/ci/badge.svg)](https://github.com/elichai/worst-executor/actions)
+[![Build status](https://github.com/elichai/worst-executor/actions/workflows/ci.yaml/badge.svg)](https://github.com/elichai/worst-executor/actions)
 [![Latest version](https://img.shields.io/crates/v/worst-executor.svg)](https://crates.io/crates/worst-executor)
 ![License](https://img.shields.io/crates/l/worst-executor.svg)
 [![dependency status](https://deps.rs/repo/github/elichai/worst-executor/status.svg)](https://deps.rs/repo/github/elichai/worst-executor)
@@ -52,6 +52,23 @@ to handle the control flow of your program, while always running on a single thr
 ```rust
 use async_net::{TcpListener, TcpStream};
 use futures::{stream::FuturesUnordered, AsyncReadExt, AsyncWriteExt, StreamExt};
+use worst_executor::block_on;
+
+block_on(async {
+    let listener = TcpListener::bind("127.0.0.1:8080").await.unwrap();
+    let mut connection_handlers = FuturesUnordered::new();
+    // This stream is infinite so it's OK to call fuse.
+    let mut listener = listener.incoming().fuse();
+    loop {
+        futures::select! {
+            new_connection = listener.select_next_some() => connection_handlers.push(handle_connection(new_connection?)),
+            socket = connection_handlers.select_next_some() =>
+                if let Some(socket) = socket {
+                    connection_handlers.push(handle_connection(socket));
+                },
+        }
+    }
+})
 
 async fn handle_connection(mut stream: TcpStream) -> Option<TcpStream> {
     let mut buf = [0u8; 1024];
@@ -69,20 +86,4 @@ async fn handle_connection(mut stream: TcpStream) -> Option<TcpStream> {
             .map(|()| stream)
             .ok()
 }
-
-worst_executor::block_on(async {
-    let listener = TcpListener::bind("127.0.0.1:8080").await.unwrap();
-    let mut connection_handlers = FuturesUnordered::new();
-    // This stream is inifinite so same to call fuse.
-    let mut listener = listener.incoming().fuse();
-    loop {
-        futures::select! {
-            new_connection = listener.select_next_some() => connection_handlers.push(handle_connection(new_connection?)),
-            socket = connection_handlers.select_next_some() => 
-                if let Some(socket) = socket {
-                    connection_handlers.push(handle_connection(socket));
-                },
-        }
-    }
-})
 ```

src/lib.rs

@@ -19,20 +19,25 @@
 //! Currently this library requires rust *nightly* for the `pin` macro, the `join` macro(used in tests) and the `const_waker` feature (required for complete optimization of `block_on`)
 //!
 //! # Examples
-//! ```rust
+//!
+//! ## Block on a simple future
+//! ```
 //! use worst_executor::block_on;
 //!
 //! let val = block_on(async { 42 });
 //! assert_eq!(val, 42);
 //! ```
 //!
-//! ```rust
+//! ## Receive and send messages through a channel
+//!
+//! This works in an event-loop style, each time checking if it can send or recieve a message.
+//! ```
 //! #![feature(future_join)]
-//! use worst_executor::block_on;
 //! use core::future::join;
+//! use worst_executor::block_on;
 //!
-//!  let (sender, receiver) = async_channel::bounded(1);
-//!  block_on(async {
+//! let (sender, receiver) = async_channel::bounded(1);
+//! block_on(async {
 //!     let send_20_fut = async {
 //!         for i in 0..20 {
 //!             sender.send(i).await.unwrap();
@@ -44,7 +49,51 @@
 //!         }
 //!     };
 //!     join!(send_20_fut, recv_20_fut).await;
-//!  });
+//! });
+//! ```
+//!
+//! ## A single threaded TCP server
+//! ```no_run
+//! use async_net::{TcpListener, TcpStream};
+//! use futures::{stream::FuturesUnordered, AsyncReadExt, AsyncWriteExt, StreamExt};
+//! use worst_executor::block_on;
+//!
+//! # fn main() -> std::io::Result<()> {
+//! block_on(async {
+//!     let listener = TcpListener::bind("127.0.0.1:8080").await.unwrap();
+//!     let mut connection_handlers = FuturesUnordered::new();
+//!     // This stream is infinite so it's OK to call fuse.
+//!     let mut listener = listener.incoming().fuse();
+//!     loop {
+//!         futures::select! {
+//!             new_connection = listener.select_next_some() => connection_handlers.push(handle_connection(new_connection?)),
+//!             socket = connection_handlers.select_next_some() =>
+//!                 if let Some(socket) = socket {
+//!                     connection_handlers.push(handle_connection(socket));
+//!                 },
+//!         }
+//!     }
+//! })
+//! # }
+//!
+//! async fn handle_connection(mut stream: TcpStream) -> Option<TcpStream> {
+//!    let mut buf = [0u8; 1024];
+//!    let n = match stream.read(&mut buf).await {
+//!        Ok(n) if n == 0 => return Some(stream),
+//!        Ok(n) => n,
+//!        Err(e) => {
+//!            eprintln!("failed to read from the socket {e:?}");
+//!            return None;
+//!        }
+//!    };
+//!    // Write the data back
+//!    stream
+//!        .write_all(&buf[0..n])
+//!        .await
+//!        .map_err(|e| eprintln!("failed to write to the socket {e:?}"))
+//!        .map(|()| stream)
+//!        .ok()
+//! }
 //! ```
 
 #![cfg_attr(not(test), no_std)]
@@ -62,13 +111,12 @@ use core::{hint, pin::pin};
 /// It will not do any scheduling, nor will it launch any threads.
 ///
 /// # Examples
-/// ```rust
+/// ```
 /// use worst_executor::block_on;
 /// block_on(async {
-///    println!("Hello, world!");
+///     println!("Hello, world!");
 /// })
 /// ```
-///
 pub fn block_on<F: Future>(f: F) -> F::Output {
     static WAKER: Waker = {
         const RAW_WAKER: RawWaker = RawWaker::new(null(), &RawWakerVTable::new(|_| RAW_WAKER, |_| (), |_| (), |_| ()));