src/tutorial,examples/: Enhance docs on multiaddrs (#2187)

Co-authored-by: Max Inden <mail@max-inden.de>

examples/chat.rs

@@ -30,15 +30,15 @@
 //!
 //! # If they don't automatically connect
 //!
-//! If the nodes don't automatically connect, take note of the listening address of the first
-//! instance and start the second with this address as the first argument. In the first terminal
-//! window, run:
+//! If the nodes don't automatically connect, take note of the listening addresses of the first
+//! instance and start the second with one of the addresses as the first argument. In the first 
+//! terminal window, run:
 //!
 //! ```sh
 //! cargo run --example chat
 //! ```
 //!
-//! It will print the PeerId and the listening address, e.g. `Listening on
+//! It will print the PeerId and the listening addresses, e.g. `Listening on
 //! "/ip4/0.0.0.0/tcp/24915"`
 //!
 //! In the second terminal window, start a new instance of the example with:

examples/gossipsub-chat.rs

@@ -27,15 +27,15 @@
 //! Dialing any of the other peers will propagate the new participant to all
 //! chat members and everyone will receive all messages.
 //!
-//! In order to get the nodes to connect, take note of the listening address of the first
-//! instance and start the second with this address as the first argument. In the first terminal
-//! window, run:
+//! In order to get the nodes to connect, take note of the listening addresses of the first
+//! instance and start the second with one of the addresses as the first argument. In the first 
+//! terminal window, run:
 //!
 //! ```sh
 //! cargo run --example gossipsub-chat
 //! ```
 //!
-//! It will print the [`PeerId`] and the listening address, e.g. `Listening on
+//! It will print the [`PeerId`] and the listening addresses, e.g. `Listening on
 //! "/ip4/0.0.0.0/tcp/24915"`
 //!
 //! In the second terminal window, start a new instance of the example with:

examples/ping.rs

@@ -28,7 +28,7 @@
 //! cargo run --example ping
 //! ```
 //!
-//! It will print the PeerId and the listening address, e.g. `Listening on
+//! It will print the PeerId and the listening addresses, e.g. `Listening on
 //! "/ip4/0.0.0.0/tcp/24915"`
 //!
 //! In the second terminal window, start a new instance of the example with:

src/tutorial.rs

@@ -209,7 +209,14 @@
 //! [`Multiaddr`] can be found on https://docs.libp2p.io/concepts/addressing/
 //! and its specification repository https://github.com/multiformats/multiaddr.
 //!
-//! Let's make our local node listen on all interfaces as well as a random port.
+//! Let's make our local node listen on a new socket.
+//! This socket is listening on multiple network interfaces at the same time. For
+//! each network interface, a new listening address is created, these may change
+//! over time as interfaces become available or unavailable.
+//! For example in case of our TCP transport, it may (among others) listen on the
+//! loopback interface (localhost) `/ip4/127.0.0.1/tcp/24915` as well as the local
+//! network `/ip4/192.168.178.25tcp/24915`.
+//!
 //! In addition, if provided on the CLI, let's instruct our local node to dial a
 //! remote peer.
 //!
@@ -325,17 +332,26 @@
 //! cargo run --example ping
 //! ```
 //!
-//! It will print the PeerId and the listening address, e.g. `Listening on
-//! "/ip4/127.0.0.1/tcp/24915"`
+//! It will print the PeerId and the new listening addresses, e.g.
+//! ```sh
+//! Local peer id: PeerId("12D3KooWT1As4mwh3KYBnNTw9bSrRbYQGJTm9SSte82JSumqgCQG")
+//! Listening on "/ip4/127.0.0.1/tcp/24915"
+//! Listening on "/ip4/192.168.178.25/tcp/24915"
+//! Listening on "/ip4/172.17.0.1/tcp/24915"
+//! Listening on "/ip6/::1/tcp/24915"
+//! ```
 //!
 //! In the second terminal window, start a new instance of the example with:
 //!
 //! ```sh
 //! cargo run --example ping -- /ip4/127.0.0.1/tcp/24915
 //! ```
 //!
-//! Note: The [`Multiaddr`] at the end being the [`Multiaddr`] printed earlier
-//! in terminal window one.
+//! Note: The [`Multiaddr`] at the end being one of the [`Multiaddr`] printed
+//! earlier in terminal window one.
+//! Both peers have to be in the same network with which the address is associated. 
+//! In our case any printed addresses can be used, as both peers run on the same 
+//! device.
 //!
 //! The two nodes will establish a connection and send each other ping and pong
 //! messages every 15 seconds.