From af8c474819c3a2878a86ce145d351d7c9e42f4e7 Mon Sep 17 00:00:00 2001
From: Floris Bruynooghe <flub@n0.computer>
Date: Thu, 17 Oct 2024 16:37:01 +0200
Subject: [PATCH] docs(iroh-net): Some more example tweaking (#2811)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

## Description

This leads the docs with an example, for those poor folks who don't
like text.


## Breaking Changes

None

## Notes & open questions

<!-- Any notes, remarks or open questions you have to make about the PR.
-->

## Change checklist

- [x] Self-review.
- [x] Documentation updates following the [style
guide](https://rust-lang.github.io/rfcs/1574-more-api-documentation-conventions.html#appendix-a-full-conventions-text),
if relevant.
- [x] Tests if relevant.
- [x] All breaking changes documented.

---------

Co-authored-by: Philipp Krüger <philipp.krueger1@gmail.com>
---
 iroh-net/src/lib.rs | 43 +++++++++++++++++++++++++++++++++++++++----
 1 file changed, 39 insertions(+), 4 deletions(-)

diff --git a/iroh-net/src/lib.rs b/iroh-net/src/lib.rs
index e01bb2bb16..5769a94bf0 100644
--- a/iroh-net/src/lib.rs
+++ b/iroh-net/src/lib.rs
@@ -4,6 +4,42 @@
 //! interface to [QUIC] connections and streams to the user, while implementing direct
 //! connectivity using [hole punching] complemented by relay servers under the hood.
 //!
+//! Connecting to a remote node looks roughly like this:
+//!
+//! ```no_run
+//! # use iroh_net::{Endpoint, NodeAddr};
+//! # async fn wrapper() -> testresult::TestResult {
+//! let addr: NodeAddr = todo!();
+//! let ep = Endpoint::builder().bind().await?;
+//! let conn = ep.connect(addr, b"my-alpn").await?;
+//! let mut send_stream = conn.open_uni().await?;
+//! send_stream.write_all(b"msg").await?;
+//! # Ok(())
+//! # }
+//! ```
+//!
+//! The other side can accept incoming connections like this:
+//!
+//! ```no_run
+//! # use iroh_net::{Endpoint, NodeAddr};
+//! # async fn wrapper() -> testresult::TestResult {
+//! let ep = Endpoint::builder()
+//!     .alpns(vec![b"my-alpn".to_vec()])
+//!     .bind()
+//!     .await?;
+//! let conn = ep.accept().await.ok_or("err")?.await?;
+//! let mut recv_stream = conn.accept_uni().await?;
+//! let mut buf = [0u8; 3];
+//! recv_stream.read_exact(&mut buf).await?;
+//! # Ok(())
+//! # }
+//! ```
+//!
+//! Of course you can also use [bi-directional streams] or any other features from QUIC.
+//!
+//! For more elaborate examples, see [below](#examples) or the examples directory in
+//! the source repository.
+//!
 //!
 //! # Connection Establishment
 //!
@@ -132,8 +168,7 @@
 //!     let (mut send_stream, mut recv_stream) = conn.open_bi().await?;
 //!     send_stream.write_all(b"hello").await?;
 //!     send_stream.finish()?;
-//!     let msg = recv_stream.read_to_end(10).await?;
-//!     println!("Server message: {}", String::from_utf8_lossy(&msg));
+//!     let _msg = recv_stream.read_to_end(10).await?;
 //!
 //!     // Gracefully close the connection and endpoint.
 //!     conn.close(1u8.into(), b"done");
@@ -161,8 +196,7 @@
 //!     // Accept a QUIC connection, accept a bi-directional stream, exchange messages.
 //!     let conn = ep.accept().await.context("no incoming connection")?.await?;
 //!     let (mut send_stream, mut recv_stream) = conn.accept_bi().await?;
-//!     let msg = recv_stream.read_to_end(10).await?;
-//!     println!("Client message: {}", String::from_utf8_lossy(&msg));
+//!     let _msg = recv_stream.read_to_end(10).await?;
 //!     send_stream.write_all(b"world").await?;
 //!     send_stream.finish()?;
 //!
@@ -177,6 +211,7 @@
 //!
 //!
 //! [QUIC]: https://quickwg.org
+//! [bi-directional streams]: crate::endpoint::Connection::open_bi
 //! [`NodeTicket`]: crate::ticket::NodeTicket
 //! [hole punching]: https://en.wikipedia.org/wiki/Hole_punching_(networking)
 //! [socket addresses]: https://doc.rust-lang.org/stable/std/net/enum.SocketAddr.html