docs: Format code in doc comments (#2895)

## Description

This enables the unstable rustfmt option to format the code in docs.
Should make our examples a lot more consistent.

## Breaking Changes

<!-- Optional, if there are any breaking changes document them,
including how to migrate older code. -->

## Notes & open questions

This is unstable, so there might be some churn or bad results.  But I
don't think the churn should be much of an issue for us.

## 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.
- [x] Tests if relevant.
- [x] All breaking changes documented.

Author: flub

Makefile.toml

@@ -10,7 +10,7 @@ args = [
      "--config",
      "unstable_features=true",
      "--config",
-     "imports_granularity=Crate,group_imports=StdExternalCrate,reorder_imports=true",
+     "imports_granularity=Crate,group_imports=StdExternalCrate,reorder_imports=true,format_code_in_doc_comments=true",
 ]
 
 [tasks.format-check]
@@ -24,5 +24,5 @@ args = [
      "--config",
      "unstable_features=true",
      "--config",
-     "imports_granularity=Crate,group_imports=StdExternalCrate,reorder_imports=true",
+     "imports_granularity=Crate,group_imports=StdExternalCrate,reorder_imports=true,format_code_in_doc_comments=true",
 ]

iroh-cli/tests/cli.rs

@@ -865,7 +865,8 @@ fn match_provide_output<T: Read>(
 ///         (r"hello world!", 1),
 ///         (r"\S*$", 1),
 ///         (r"\d{2}/\d{2}/\d{4}", 3),
-///     ]);
+///     ],
+/// );
 /// ```
 fn assert_matches_line<R: BufRead, I>(reader: R, expressions: I) -> Vec<(usize, Vec<String>)>
 where

iroh-dns-server/src/http.rs

@@ -237,7 +237,6 @@ pub(crate) fn create_app(state: AppState, rate_limit_config: &RateLimitConfig) -
 }
 
 /// Record request metrics.
-///
 // TODO:
 // * Request duration would be much better tracked as a histogram.
 // * It would be great to attach labels to the metrics, so that the recorded metrics

iroh-metrics/src/metrics.rs

@@ -13,8 +13,10 @@
 //!
 //! # Example:
 //! ```rust
-//! use iroh_metrics::{inc, inc_by};
-//! use iroh_metrics::core::{Core, Metric, Counter};
+//! use iroh_metrics::{
+//!     core::{Core, Counter, Metric},
+//!     inc, inc_by,
+//! };
 //! use struct_iterable::Iterable;
 //!
 //! #[derive(Debug, Clone, Iterable)]
@@ -25,15 +27,17 @@
 //! impl Default for Metrics {
 //!     fn default() -> Self {
 //!         Self {
-//!             things_added: Counter::new("things_added tracks the number of things we have added"),
+//!             things_added: Counter::new(
+//!                 "things_added tracks the number of things we have added",
+//!             ),
 //!         }
 //!     }
 //! }
 //!
 //! impl Metric for Metrics {
-//!    fn name() -> &'static str {
+//!     fn name() -> &'static str {
 //!         "my_metrics"
-//!    }
+//!     }
 //! }
 //!
 //! Core::init(|reg, metrics| {

iroh-net/src/discovery.rs

@@ -46,11 +46,11 @@
 //! [`PkarrPublisher`] and [`DnsDiscovery`]:
 //!
 //! ```no_run
-//! use iroh_net::discovery::dns::DnsDiscovery;
-//! use iroh_net::discovery::pkarr::PkarrPublisher;
-//! use iroh_net::discovery::ConcurrentDiscovery;
-//! use iroh_net::key::SecretKey;
-//! use iroh_net::Endpoint;
+//! use iroh_net::{
+//!     discovery::{dns::DnsDiscovery, pkarr::PkarrPublisher, ConcurrentDiscovery},
+//!     key::SecretKey,
+//!     Endpoint,
+//! };
 //!
 //! # async fn wrapper() -> anyhow::Result<()> {
 //! let secret_key = SecretKey::generate();

iroh-net/src/discovery/local_swarm_discovery.rs

@@ -7,29 +7,28 @@
 //!
 //! ```
 //! use std::time::Duration;
-//! use iroh_net::endpoint::{Source, Endpoint};
+//!
+//! use iroh_net::endpoint::{Endpoint, Source};
 //!
 //! #[tokio::main]
 //! async fn main() {
-//!   let recent = Duration::from_secs(600); // 10 minutes in seconds
+//!     let recent = Duration::from_secs(600); // 10 minutes in seconds
 //!
-//!   let endpoint = Endpoint::builder().bind().await.unwrap();
-//!   let remotes = endpoint.remote_info_iter();
-//!   let locally_discovered: Vec<_> = remotes
-//!      .filter(|remote| {
-//!          remote
-//!              .sources()
-//!              .iter()
-//!              .any(|(source, duration)| {
-//!                  if let Source::Discovery { name } = source {
-//!                      name == iroh_net::discovery::local_swarm_discovery::NAME && *duration <= recent
-//!                  } else {
-//!                      false
-//!                  }
-//!              })
-//!    })
-//!       .collect();
-//!   println!("locally discovered nodes: {locally_discovered:?}");
+//!     let endpoint = Endpoint::builder().bind().await.unwrap();
+//!     let remotes = endpoint.remote_info_iter();
+//!     let locally_discovered: Vec<_> = remotes
+//!         .filter(|remote| {
+//!             remote.sources().iter().any(|(source, duration)| {
+//!                 if let Source::Discovery { name } = source {
+//!                     name == iroh_net::discovery::local_swarm_discovery::NAME
+//!                         && *duration <= recent
+//!                 } else {
+//!                     false
+//!                 }
+//!             })
+//!         })
+//!         .collect();
+//!     println!("locally discovered nodes: {locally_discovered:?}");
 //! }
 //! ```
 use std::{

iroh-net/src/endpoint.rs

@@ -845,7 +845,7 @@ impl Endpoint {
     ///
     /// # let rt = tokio::runtime::Builder::new_current_thread().enable_all().build().unwrap();
     /// # rt.block_on(async move {
-    /// let mep =  Endpoint::builder().bind().await.unwrap();
+    /// let mep = Endpoint::builder().bind().await.unwrap();
     /// let _addrs = mep.direct_addresses().next().await;
     /// # });
     /// ```

iroh-net/src/lib.rs

@@ -184,8 +184,7 @@
 //! ```no_run
 //! use anyhow::{Context, Result};
 //! use futures_lite::StreamExt;
-//! use iroh_net::ticket::NodeTicket;
-//! use iroh_net::{Endpoint, NodeAddr};
+//! use iroh_net::{ticket::NodeTicket, Endpoint, NodeAddr};
 //!
 //! async fn accept() -> Result<()> {
 //!     // To accept connections at least one ALPN must be configured.

iroh-net/src/relay/codec.rs

@@ -60,7 +60,6 @@ pub(super) const PROTOCOL_VERSION: usize = 3;
 ///  * client responds to any FrameType::Ping with a FrameType::Pong
 ///  * clients sends FrameType::SendPacket
 ///  * server then sends FrameType::RecvPacket to recipient
-///
 
 const PREFERRED: u8 = 1u8;
 /// indicates this is NOT the client's home node

iroh-net/src/relay/server/clients.rs

@@ -18,7 +18,6 @@ use crate::key::PublicKey;
 const RETRIES: usize = 3;
 
 /// Represents a connection to a client.
-///
 // TODO: expand to allow for _multiple connections_ associated with a single PublicKey. This
 // introduces some questions around which connection should be prioritized when forwarding packets
 //