docs: update instructions for running rust examples

iroh/README.md

@@ -19,7 +19,7 @@ iroh = { version = "...", default-features = false }
 
 ## Running Examples
 
-examples are located in `iroh/examples`. Some have their own cargo.toml to show different use cases, and as such are shipped as their own packages. For these run them with `cargo run --package`. eg: `cargo run --package hello-world`
+Examples are located in `iroh/examples`. Run them with `cargo run --example`. eg: `cargo run --example hello-world`. At the top of each example file is a comment describing how to run the example.
 
 # License
 

iroh/examples/client.rs

@@ -1,3 +1,10 @@
+//! This example shows the shortest path to working with documents in iroh. This example creates a
+//! document and sets an entry with key: "hello", value: "world". The document is completely local.
+//!
+//! The iroh node that creates the document is backed by an in-memory database and a random peer ID
+//!
+//! run this example from the project root:
+//!     $ cargo run --example client
 use indicatif::HumanBytes;
 use iroh::node::Node;
 use iroh_bytes::util::runtime;

iroh/examples/dump-blob-fsm.rs

@@ -1,6 +1,11 @@
 //! An example how to download a single blob from a node and write it to stdout.
 //!
 //! This is using the get finite state machine directly.
+//! Run this example on any `iroh get` ticket. You can create a "hello world" ticket with:
+//!     $ cargo run --example hello-world
+//! hello-world will give you a "ticket" argument & example to use with `cargo run -- get --ticket`
+//! copy that ticket value (the long string after `--ticket`) & feed it to this example:
+//!     $ cargo run --example dump-blob-fsm <ticket>
 use std::env::args;
 use std::str::FromStr;
 

iroh/examples/dump-blob-stream.rs

@@ -1,6 +1,11 @@
 //! An example how to download a single blob from a node and write it to stdout.
 //!
 //! This is using a helper method to stream the blob.
+//! Run this example on any `iroh get` ticket. You can create a "hello world" ticket with:
+//!     $ cargo run --example hello-world
+//! hello-world will give you a "ticket" argument & example to use with `cargo run -- get --ticket`
+//! copy that ticket & feed it to this example:
+//!     $ cargo run --example dump-blob-stream <ticket>
 use std::env::args;
 use std::io;
 use std::str::FromStr;

iroh/examples/hello-world.rs

@@ -3,8 +3,8 @@
 //! This can be downloaded using the iroh CLI.
 //!
 //! This is using an in memory database and a random peer id.
-//! //! run this example from the project root:
-//!     $ cargo run -p hello-world
+//! run this example from the project root:
+//!     $ cargo run --example hello-world
 use iroh::bytes::util::runtime;
 use tracing_subscriber::{prelude::*, EnvFilter};
 

iroh/examples/rpc.rs

@@ -1,4 +1,11 @@
 //! An example that runs an iroh node that can be controlled via RPC.
+//!
+//! Run this example with
+//!   $ cargo run --example rpc
+//! Then in another terminal, run any of the normal iroh CLI commands, which you can run from
+//! cargo as well:
+//!   $ cargo run node stats
+//! The `node stats` command will reach out over RPC to the node constructed in the example
 use std::net::{Ipv4Addr, SocketAddr, SocketAddrV4};
 
 use clap::Parser;

iroh/examples/sync.rs

@@ -3,6 +3,10 @@
 //! By default a new peer id is created when starting the example. To reuse your identity,
 //! set the `--secret-key` CLI flag with the secret key printed on a previous invocation.
 //!
+//! Run with:
+//!   $ cargo run --example sync --features=example-sync
+//! Then follow the instructions printed
+//!
 //! You can use this with a local DERP server. To do so, run
 //! `cargo run --bin derper -- --dev`
 //! and then set the `-d http://localhost:3340` flag on this example.