feat(iroh): Improve documentation and canonicalize docs in iroh::client

iroh/src/client.rs

@@ -1,4 +1,6 @@
 //! Client to an Iroh node.
+//!
+//! See the documentation for [`Iroh`] for more information.
 
 use futures_lite::{Stream, StreamExt};
 use ref_cast::RefCast;
@@ -21,11 +23,23 @@ pub mod gossip;
 pub mod node;
 pub mod tags;
 
+// Keep this type exposed, otherwise every occurrence of `RpcClient` in the API
+// will show up as `RpcClient<RpcService, Connection<RpcService>>` in the docs.
 /// Iroh rpc client - boxed so that we can have a concrete type.
-pub(crate) type RpcClient =
+pub type RpcClient =
     quic_rpc::RpcClient<RpcService, quic_rpc::transport::boxed::Connection<RpcService>>;
 
-/// Iroh client.
+/// An iroh client.
+///
+/// There are three ways to obtain this client, depending on which context
+/// you're running in relative to the main [`Node`](crate::node::Node):
+///
+/// 1. If you just spawned the client in rust the same process and have a reference to it:
+///    Use [`Node::client()`](crate::node::Node::client).
+/// 2. If the main node wasn't spawned in the same process, but on the same machine:
+///    Use [`Iroh::connect_path`].
+/// 3. If the main node was spawned somewhere else and has been made accessible via IP:
+///    Use [`Iroh::connect_addr`].
 #[derive(Debug, Clone)]
 pub struct Iroh {
     rpc: RpcClient,
@@ -40,37 +54,42 @@ impl Deref for Iroh {
 }
 
 impl Iroh {
-    /// Create a new high-level client to a Iroh node from the low-level RPC client.
+    /// Creates a new high-level client to a Iroh node from the low-level RPC client.
+    ///
+    /// Prefer using [`Node::client()`](crate::node::Node::client), [`Iroh::connect_path`]
+    /// or [`Iroh::connect_addr`] instead of calling this function.
+    ///
+    /// See also the [`Iroh`] struct documentation.
     pub fn new(rpc: RpcClient) -> Self {
         Self { rpc }
     }
 
-    /// Blobs client
+    /// Returns the blobs client.
     pub fn blobs(&self) -> &blobs::Client {
         blobs::Client::ref_cast(&self.rpc)
     }
 
-    /// Docs client
+    /// Returns the docs client.
     pub fn docs(&self) -> &docs::Client {
         docs::Client::ref_cast(&self.rpc)
     }
 
-    /// Authors client
+    /// Returns the authors client.
     pub fn authors(&self) -> &authors::Client {
         authors::Client::ref_cast(&self.rpc)
     }
 
-    /// Tags client
+    /// Returns the tags client.
     pub fn tags(&self) -> &tags::Client {
         tags::Client::ref_cast(&self.rpc)
     }
 
-    /// Gossip client
+    /// Returns the gossip client.
     pub fn gossip(&self) -> &gossip::Client {
         gossip::Client::ref_cast(&self.rpc)
     }
 
-    /// Node client
+    /// Returns the node client.
     pub fn node(&self) -> &node::Client {
         node::Client::ref_cast(&self.rpc)
     }

iroh/src/client/authors.rs

@@ -1,4 +1,8 @@
 //! API for author management.
+//!
+//! The main entry point is the [`Client`].
+//!
+//! You obtain a [`Client`] via [`Iroh::authors()`](crate::client::Iroh::authors).
 
 use anyhow::Result;
 use futures_lite::{stream::StreamExt, Stream};
@@ -20,7 +24,7 @@ pub struct Client {
 }
 
 impl Client {
-    /// Create a new document author.
+    /// Creates a new document author.
     ///
     /// You likely want to save the returned [`AuthorId`] somewhere so that you can use this author
     /// again.
@@ -42,7 +46,7 @@ impl Client {
         Ok(res.author_id)
     }
 
-    /// Set the node-wide default author.
+    /// Sets the node-wide default author.
     ///
     /// If the author does not exist, an error is returned.
     ///
@@ -53,23 +57,25 @@ impl Client {
         Ok(())
     }
 
-    /// List document authors for which we have a secret key.
+    /// Lists document authors for which we have a secret key.
+    ///
+    /// It's only possible to create writes from authors that we have the secret key of.
     pub async fn list(&self) -> Result<impl Stream<Item = Result<AuthorId>>> {
         let stream = self.rpc.server_streaming(ListRequest {}).await?;
         Ok(flatten(stream).map(|res| res.map(|res| res.author_id)))
     }
 
-    /// Export the given author.
+    /// Exports the given author.
     ///
-    /// Warning: This contains sensitive data.
+    /// Warning: The [`Author`] struct contains sensitive data.
     pub async fn export(&self, author: AuthorId) -> Result<Option<Author>> {
         let res = self.rpc.rpc(ExportRequest { author }).await??;
         Ok(res.author)
     }
 
-    /// Import the given author.
+    /// Imports the given author.
     ///
-    /// Warning: This contains sensitive data.
+    /// Warning: The [`Author`] struct contains sensitive data.
     pub async fn import(&self, author: Author) -> Result<()> {
         self.rpc.rpc(ImportRequest { author }).await??;
         Ok(())

iroh/src/client/blobs.rs

@@ -2,6 +2,8 @@
 //!
 //! The main entry point is the [`Client`].
 //!
+//! You obtain a [`Client`] via [`Iroh::blobs()`](crate::client::Iroh::blobs).
+//!
 //! ## Interacting with the local blob store
 //!
 //! ### Importing data