docs(iroh): Expand module level documentation in iroh #2463
Conversation
before it was hidden and therefore unusable
rklaehn
changed the title
This reverts commit 084de5c.
iroh/src/client/blobs.rs
Outdated
| //! There are several ways to export data from the local blob store: | ||
| //! | ||
| //! - [`read_to_bytes`](Client::read_to_bytes) reads data into memory. | ||
| //! - [`read`](Client::read) creates a reader to read data from. |
iroh/src/client/blobs.rs
Outdated
| //! | ||
| //! - [`download`](Client::download) downloads data from a remote node. | ||
| //! - [`share`](Client::share) | ||
| //! allows creating a ticket to share data with a remote node. |
| //! | ||
| //! The main entry point is the [`Client`]. | ||
| //! | ||
| //! ## Interacting with the local blob store |
There was a problem hiding this comment.
Are you supposed to skip the top-level header? I think I've always seen # as the first header indentation.
| //! | ||
| //! There are several ways to import data into the local blob store: | ||
| //! | ||
| //! - [`add_bytes`](Client::add_bytes) |
There was a problem hiding this comment.
I'd have written this as `[`Client::add_bytes`]` directly. The style guide is also not really in favour of writing the links inline and prefers them via references.
| //! There are several ways to export data from the local blob store: | ||
| //! | ||
| //! - [`read_to_bytes`](Client::read_to_bytes) reads data into memory. | ||
| //! - [`read`](Client::read) creates a [reader](Reader) to read data from. |
There was a problem hiding this comment.
| //! - [`read`](Client::read) creates a [reader](Reader) to read data from. | |
| //! - [`read`](Client::read) creates a [`Reader`] to read data from. |
This would make more clear that you're linking directly to a type which I usually prefer. That's just my personal preference though, no written rule.
|
|
||
| //! | ||
| //! The purpose of tags is to mark information as important. Currently this is | ||
| //! used for blobs. |
There was a problem hiding this comment.
Is it described anywhere how this is used for blobs? Why not give a short description here as an example that gives a general idea of how tags are used?
| //! available over the network. | ||
| //! | ||
| //! ```rust | ||
| //! # async fn run() -> anyhow::Result<()> { |
There was a problem hiding this comment.
wait, what? We can just write async fn in doc tests and it'll work? How did I now know that?
| //! | ||
| //! ### Iroh node | ||
| //! | ||
| //! To create an iroh [Node](crate::node::Node), you use the |
There was a problem hiding this comment.
style-guide prefers reference-style links rather than inline
Description
Breaking Changes
None, I am going to do those in a separate PR
Notes & open questions
Change checklist
Tests if relevant.All breaking changes documented.