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.

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
 //

iroh/src/client/net.rs

@@ -39,7 +39,11 @@ use crate::rpc_protocol::net::{
 /// # Examples
 /// ```
 /// use std::str::FromStr;
-/// use iroh_base::{key::NodeId, node_addr::{RelayUrl, NodeAddr}};
+///
+/// use iroh_base::{
+///     key::NodeId,
+///     node_addr::{NodeAddr, RelayUrl},
+/// };
 /// use url::Url;
 ///
 /// # async fn run() -> anyhow::Result<()> {
@@ -50,12 +54,13 @@ use crate::rpc_protocol::net::{
 /// // 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
-///   ["120.0.0.1:0".parse().unwrap()],
+///     // the node_id
+///     NodeId::from_str("ae58ff8833241ac82d6ff7611046ed67b5072d142c588d0063e942d9a75502b6")
+///         .unwrap(),
+///     // the home relay
+///     Some(relay_url),
+///     // the direct addresses
+///     ["120.0.0.1:0".parse().unwrap()],
 /// );
 /// net_client.add_node_addr(addr).await?;
 /// // Shut down the node. Passing `true` will force the shutdown, passing in

iroh/src/lib.rs

@@ -87,7 +87,6 @@
 //!
 //! - `metrics`: Enable metrics collection. Enabled by default.
 //! - `fs-store`: Enables the disk based storage backend for `iroh-blobs`. Enabled by default.
-//!
 #![cfg_attr(iroh_docsrs, feature(doc_cfg))]
 #![deny(missing_docs, rustdoc::broken_intra_doc_links)]
 

iroh/src/node/builder.rs

@@ -799,8 +799,6 @@ impl<D: iroh_blobs::store::Store> ProtocolBuilder<D> {
     /// # Ok(())
     /// # }
     /// ```
-    ///
-    ///
     pub fn accept(mut self, alpn: Vec<u8>, handler: Arc<dyn ProtocolHandler>) -> Self {
         self.router = self.router.accept(alpn, handler);
         self

iroh/src/util/fs.rs

@@ -167,7 +167,6 @@ pub struct PathContent {
 }
 
 /// Walks the directory to get the total size and number of files in directory or file
-///
 // TODO: possible combine with `scan_dir`
 pub fn path_content_info(path: impl AsRef<Path>) -> anyhow::Result<PathContent> {
     path_content_info0(path)

net-tools/portmapper/src/pcp/protocol/request.rs

@@ -10,7 +10,6 @@ use super::{
 /// A PCP Request.
 ///
 /// See [RFC 6887 Request Header](https://datatracker.ietf.org/doc/html/rfc6887#section-7.1)
-///
 // NOTE: PCP Options are optional, and currently not used in this code, thus not implemented
 #[derive(Debug, PartialEq, Eq)]
 pub struct Request {

net-tools/portmapper/src/pcp/protocol/response.rs

@@ -105,7 +105,6 @@ impl From<ResultCode> for u8 {
 /// A PCP successful Response/Notification.
 ///
 /// See [RFC 6887 Response Header](https://datatracker.ietf.org/doc/html/rfc6887#section-7.2)
-///
 // NOTE: first two fields are *currently* not used, but are useful for debug purposes
 #[allow(unused)]
 #[derive(Debug, PartialEq, Eq)]