From 55836fa5ca56fe6964be52046bb0c7f77e62b647 Mon Sep 17 00:00:00 2001
From: Kasey <kasey@n0.computer>
Date: Mon, 5 Aug 2024 13:42:10 -0400
Subject: [PATCH] docs(iroh): add documentations and examples for the
 `iroh::node::Client` (#2582)

## Description

Happy Docs Day! Added documentation to the `iroh::node::Client`,
including examples.

## 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.

---------

Co-authored-by: Kasey Huizinga <ramfox@Kaseys-MBP.lan>
---
 Cargo.lock              |  1 +
 iroh/Cargo.toml         |  3 ++
 iroh/src/client/node.rs | 81 ++++++++++++++++++++++++++++++++++++++++-
 3 files changed, 84 insertions(+), 1 deletion(-)

diff --git a/Cargo.lock b/Cargo.lock
index af8e7a5224..32932a5825 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -2525,6 +2525,7 @@ dependencies = [
  "tokio-util",
  "tracing",
  "tracing-subscriber",
+ "url",
  "walkdir",
 ]
 
diff --git a/iroh/Cargo.toml b/iroh/Cargo.toml
index 855f65803a..69ec85d66b 100644
--- a/iroh/Cargo.toml
+++ b/iroh/Cargo.toml
@@ -59,6 +59,9 @@ indicatif = { version = "0.17", features = ["tokio"], optional = true }
 ref-cast = "1.0.23"
 console = { version = "0.15.5", optional = true }
 
+# Documentation tests
+url = { version = "2.5.0", features = ["serde"] }
+
 [features]
 default = ["metrics", "fs-store"]
 metrics = ["iroh-metrics", "iroh-blobs/metrics"]
diff --git a/iroh/src/client/node.rs b/iroh/src/client/node.rs
index 265d3c2a00..c12c5bd5bb 100644
--- a/iroh/src/client/node.rs
+++ b/iroh/src/client/node.rs
@@ -29,7 +29,86 @@ use crate::rpc_protocol::node::{
 
 use super::{flatten, RpcClient};
 
-/// Iroh node client.
+/// Iroh node Client.
+///
+/// Cheaply clonable and threadsafe. Use the iroh `node::Client` to access the
+/// iroh node methods from a different thread, process, or remote machine.
+/// The [`Iroh`](crate::client::Iroh) client dereferences to a `node::Client`,
+/// so you have access to this api from the [`Iroh`](crate::client::Iroh) client itself.
+///
+/// The `node::Client` api allows you to get information *about* the iroh node,
+/// its status, and connection status to other nodes. It also allows you to
+/// provide address information about *other* nodes to your node.
+///
+/// Obtain an iroh `node::Client` via [`Iroh::node()`](crate::client::Iroh::node).
+///
+/// It also provides a way to [shutdown](Client::shutdown) the entire iroh node.
+///
+/// # Examples
+/// ```
+/// use std::str::FromStr;
+/// use iroh_base::{key::NodeId, node_addr::{RelayUrl, NodeAddr}};
+/// use url::Url;
+///
+/// # async fn run() -> anyhow::Result<()> {
+/// // Create an iroh node:
+/// let iroh = iroh::node::Node::memory().spawn().await?;
+/// // Create a node client, a client that gives you access to `node` subsystem
+/// let node_client = iroh.client().node();
+/// // Get the node status, including its node id, addresses, the version of iroh
+/// // it is running, and more.
+/// let status = node_client.status().await?;
+/// println!("Node status: {status:?}");
+/// // Provide your node an address for another node
+/// let relay_url = RelayUrl::from(Url::parse("https://example.com").unwrap());
+/// let addr = NodeAddr::from_parts(
+///   // the node_id
+///   NodeId::from_str("ae58ff8833241ac82d6ff7611046ed67b5072d142c588d0063e942d9a75502b6").unwrap(),
+///   // the home relay
+///   Some(relay_url),
+///   // the direct addresses
+///   vec!["120.0.0.1:0".parse().unwrap()],
+/// );
+/// node_client.add_node_addr(addr).await?;
+/// // Shut down the node. Passing `true` will force the shutdown, passing in
+/// // `false` will allow the node to shut down gracefully.
+/// node_client.shutdown(false).await?;
+/// # Ok(())
+/// # }
+/// ```
+/// You can also use the `node::Client` methods from the `Iroh` client:
+///
+/// ```
+/// use std::str::FromStr;
+/// use iroh_base::{key::NodeId, node_addr::{RelayUrl, NodeAddr}};
+/// use url::Url;
+///
+/// # async fn run() -> anyhow::Result<()> {
+/// // Create an iroh node:
+/// let iroh = iroh::node::Node::memory().spawn().await?;
+/// // Create a client:
+/// let client = iroh.client();
+/// // Get the node status, including its node id, addresses, the version of iroh
+/// // it is running, and more.
+/// let status = client.status().await?;
+/// println!("Node status: {status:?}");
+/// // Provide your node an address for another node
+/// let relay_url = RelayUrl::from(Url::parse("https://example.com").unwrap());
+/// let addr = NodeAddr::from_parts(
+///   // the node_id
+///   NodeId::from_str("ae58ff8833241ac82d6ff7611046ed67b5072d142c588d0063e942d9a75502b6").unwrap(),
+///   // the home relay
+///   Some(relay_url),
+///   // the direct addresses
+///   vec!["120.0.0.1:0".parse().unwrap()],
+/// );
+/// client.add_node_addr(addr).await?;
+/// // Shut down the node. Passing `true` will force the shutdown, passing in
+/// // `false` will allow the node to shut down gracefully.
+/// client.shutdown(false).await?;
+/// # Ok(())
+/// # }
+/// ```
 #[derive(Debug, Clone, RefCast)]
 #[repr(transparent)]
 pub struct Client {