docs(iroh-net): Document cargo features needed for APIs (#2759)

## Description

This uses the feature of docs.rs to enable showing which cargo
features need to be enabled for APIs.  This is much friendlier for
users.

## Breaking Changes

None

## Notes & open questions

I'm trying to do this for the entire workspace but for some reason am
not getting this to work on other crates yet.  This is all such a
mystery and mess.  Just get this in stable rust already and do this by
default without needing extra annotations.

I'll try and do the rest of the workspace still in a followup PR, but
at least this might make the release so we get to see if it works on
actual docs.rs as well.

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

Cargo.toml

@@ -34,5 +34,15 @@ incremental = false
 [workspace.lints.rust]
 missing_debug_implementations = "warn"
 
+# We use this --cfg for documenting the cargo features on which an API
+# is available.  To preview this locally use: RUSTFLAGS="--cfg
+# iroh_docsrs cargo +nightly doc --all-features".  We use our own
+# iroh_docsrs instead of the common docsrs to avoid also enabling this
+# feature in any dependencies, because some indirect dependencies
+# require a feature enabled when using `--cfg docsrs` which we can not
+# do.  To enable for a crate set `#![cfg_attr(iroh_docsrs,
+# feature(doc_cfg))]` in the crate.
+unexpected_cfgs = { level = "warn", check-cfg = ["cfg(iroh_docsrs)"] }
+
 [workspace.lints.clippy]
 unused-async = "warn"

iroh-net/Cargo.toml

@@ -154,6 +154,7 @@ required-features = ["iroh-relay"]
 
 [package.metadata.docs.rs]
 all-features = true
+rustdoc-args = ["--cfg", "iroh_docsrs"]
 
 [[example]]
 name = "listen"

iroh-net/src/defaults.rs

@@ -196,6 +196,7 @@ pub(crate) mod timeouts {
 
         /// Maximum time the server will attempt to get a successful write to the connection.
         #[cfg(feature = "iroh-relay")]
+        #[cfg_attr(iroh_docsrs, doc(cfg(feature = "iroh-relay")))]
         pub(crate) const SERVER_WRITE_TIMEOUT: Duration = Duration::from_secs(2);
     }
 }

iroh-net/src/discovery.rs

@@ -51,6 +51,7 @@ use tracing::{debug, error_span, warn, Instrument};
 pub mod dns;
 
 #[cfg(feature = "discovery-local-network")]
+#[cfg_attr(iroh_docsrs, doc(cfg(feature = "discovery-local-network")))]
 pub mod local_swarm_discovery;
 pub mod pkarr;
 

iroh-net/src/discovery/dns.rs

@@ -15,6 +15,7 @@ pub const N0_DNS_NODE_ORIGIN_PROD: &str = "dns.iroh.link";
 pub const N0_DNS_NODE_ORIGIN_STAGING: &str = "staging-dns.iroh.link";
 /// Testing DNS node origin, must run server from [`crate::test_utils::DnsPkarrServer`].
 #[cfg(any(test, feature = "test-utils"))]
+#[cfg_attr(iroh_docsrs, doc(cfg(any(test, feature = "test-utils"))))]
 pub const TEST_DNS_NODE_ORIGIN: &str = "dns.iroh.test";
 
 const DNS_STAGGERING_MS: &[u64] = &[200, 300];

iroh-net/src/discovery/pkarr.rs

@@ -65,6 +65,7 @@ use crate::{
 };
 
 #[cfg(feature = "discovery-pkarr-dht")]
+#[cfg_attr(iroh_docsrs, doc(cfg(feature = "discovery-pkarr-dht")))]
 pub mod dht;
 
 /// The production pkarr relay run by [number 0].

iroh-net/src/endpoint.rs

@@ -59,6 +59,7 @@ const DISCOVERY_WAIT_PERIOD: Duration = Duration::from_millis(500);
 
 /// Environment variable to force the use of staging relays.
 #[cfg(not(any(test, feature = "test-utils")))]
+#[cfg_attr(iroh_docsrs, doc(cfg(not(any(test, feature = "test-utils")))))]
 const ENV_FORCE_STAGING_RELAYS: &str = "IROH_FORCE_STAGING_RELAYS";
 
 /// Builder for [`Endpoint`].
@@ -80,6 +81,7 @@ pub struct Builder {
     node_map: Option<Vec<NodeAddr>>,
     dns_resolver: Option<DnsResolver>,
     #[cfg(any(test, feature = "test-utils"))]
+    #[cfg_attr(iroh_docsrs, doc(cfg(any(test, feature = "test-utils"))))]
     insecure_skip_relay_cert_verify: bool,
     addr_v4: Option<SocketAddrV4>,
     addr_v6: Option<SocketAddrV6>,
@@ -288,6 +290,7 @@ impl Builder {
     ///
     /// May only be used in tests.
     #[cfg(any(test, feature = "test-utils"))]
+    #[cfg_attr(iroh_docsrs, doc(cfg(any(test, feature = "test-utils"))))]
     pub fn insecure_skip_relay_cert_verify(mut self, skip_verify: bool) -> Self {
         self.insecure_skip_relay_cert_verify = skip_verify;
         self

iroh-net/src/lib.rs

@@ -120,6 +120,7 @@
 
 #![recursion_limit = "256"]
 #![deny(missing_docs, rustdoc::broken_intra_doc_links)]
+#![cfg_attr(iroh_docsrs, feature(doc_cfg))]
 
 pub mod defaults;
 pub mod dialer;
@@ -146,4 +147,5 @@ pub use iroh_base::key;
 pub use iroh_base::key::NodeId;
 
 #[cfg(any(test, feature = "test-utils"))]
+#[cfg_attr(iroh_docsrs, doc(cfg(any(test, feature = "test-utils"))))]
 pub mod test_utils;

iroh-net/src/magicsock.rs

@@ -129,6 +129,7 @@ pub(crate) struct Options {
     ///
     /// May only be used in tests.
     #[cfg(any(test, feature = "test-utils"))]
+    #[cfg_attr(iroh_docsrs, doc(cfg(any(test, feature = "test-utils"))))]
     pub(crate) insecure_skip_relay_cert_verify: bool,
 }
 
@@ -243,6 +244,7 @@ pub(crate) struct MagicSock {
     ///
     /// May only be used in tests.
     #[cfg(any(test, feature = "test-utils"))]
+    #[cfg_attr(iroh_docsrs, doc(cfg(any(test, feature = "test-utils"))))]
     insecure_skip_relay_cert_verify: bool,
 }
 

iroh-net/src/metrics.rs

@@ -3,4 +3,5 @@ pub use crate::magicsock::Metrics as MagicsockMetrics;
 pub use crate::netcheck::Metrics as NetcheckMetrics;
 pub use crate::portmapper::Metrics as PortmapMetrics;
 #[cfg(feature = "iroh-relay")]
+#[cfg_attr(iroh_docsrs, doc(cfg(feature = "iroh-relay")))]
 pub use crate::relay::server::Metrics as RelayMetrics;

iroh-net/src/relay.rs

@@ -15,6 +15,7 @@ pub(crate) mod codec;
 pub mod http;
 mod map;
 #[cfg(feature = "iroh-relay")]
+#[cfg_attr(iroh_docsrs, doc(cfg(feature = "iroh-relay")))]
 pub mod server;
 
 pub use self::client::conn::{Conn as RelayConn, ReceivedMessage};

iroh-net/src/relay/client.rs

@@ -219,6 +219,7 @@ pub struct ClientBuilder {
     protocol: Protocol,
     /// Allow self-signed certificates from relay servers
     #[cfg(any(test, feature = "test-utils"))]
+    #[cfg_attr(iroh_docsrs, doc(cfg(any(test, feature = "test-utils"))))]
     insecure_skip_cert_verify: bool,
     /// HTTP Proxy
     proxy_url: Option<Url>,
@@ -291,6 +292,7 @@ impl ClientBuilder {
     ///
     /// May only be used in tests.
     #[cfg(any(test, feature = "test-utils"))]
+    #[cfg_attr(iroh_docsrs, doc(cfg(any(test, feature = "test-utils"))))]
     pub fn insecure_skip_cert_verify(mut self, skip: bool) -> Self {
         self.insecure_skip_cert_verify = skip;
         self
@@ -1049,6 +1051,7 @@ async fn resolve_host(
 
 /// Used to allow self signed certificates in tests
 #[cfg(any(test, feature = "test-utils"))]
+#[cfg_attr(iroh_docsrs, doc(cfg(any(test, feature = "test-utils"))))]
 #[derive(Debug)]
 struct NoCertVerifier;
 

iroh-net/src/relay/codec.rs

@@ -24,9 +24,11 @@ const MAX_FRAME_SIZE: usize = 1024 * 1024;
 const MAGIC: &str = "RELAY🔑";
 
 #[cfg(feature = "iroh-relay")]
+#[cfg_attr(iroh_docsrs, doc(cfg(feature = "iroh-relay")))]
 pub(super) const KEEP_ALIVE: Duration = Duration::from_secs(60);
 // TODO: what should this be?
 #[cfg(feature = "iroh-relay")]
+#[cfg_attr(iroh_docsrs, doc(cfg(feature = "iroh-relay")))]
 pub(super) const SERVER_CHANNEL_SIZE: usize = 1024 * 100;
 /// The number of packets buffered for sending per client
 pub(super) const PER_CLIENT_SEND_QUEUE_DEPTH: usize = 512; //32;
@@ -166,6 +168,7 @@ pub(crate) async fn send_client_key<S: Sink<Frame, Error = std::io::Error> + Unp
 /// Reads the `FrameType::ClientInfo` frame from the client (its proof of identity)
 /// upon it's initial connection.
 #[cfg(feature = "iroh-relay")]
+#[cfg_attr(iroh_docsrs, doc(cfg(feature = "iroh-relay")))]
 pub(super) async fn recv_client_key<S: Stream<Item = anyhow::Result<Frame>> + Unpin>(
     stream: S,
 ) -> anyhow::Result<(PublicKey, ClientInfo)> {
@@ -536,6 +539,7 @@ impl Encoder<Frame> for DerpCodec {
 /// Receives the next frame and matches the frame type. If the correct type is found returns the content,
 /// otherwise an error.
 #[cfg(feature = "iroh-relay")]
+#[cfg_attr(iroh_docsrs, doc(cfg(feature = "iroh-relay")))]
 pub(super) async fn recv_frame<S: Stream<Item = anyhow::Result<Frame>> + Unpin>(
     frame_type: FrameType,
     mut stream: S,

iroh-net/src/relay/http.rs

@@ -3,6 +3,7 @@
 pub(crate) const HTTP_UPGRADE_PROTOCOL: &str = "iroh derp http";
 pub(crate) const WEBSOCKET_UPGRADE_PROTOCOL: &str = "websocket";
 #[cfg(feature = "iroh-relay")] // only used in the server for now
+#[cfg_attr(iroh_docsrs, doc(cfg(feature = "iroh-relay")))]
 pub(crate) const SUPPORTED_WEBSOCKET_VERSION: &str = "13";
 
 /// The HTTP path under which the relay accepts relaying connections
@@ -13,10 +14,12 @@ pub const RELAY_PROBE_PATH: &str = "/relay/probe";
 /// The legacy HTTP path under which the relay used to accept relaying connections.
 /// We keep this for backwards compatibility.
 #[cfg(feature = "iroh-relay")] // legacy paths only used on server-side for backwards compat
+#[cfg_attr(iroh_docsrs, doc(cfg(feature = "iroh-relay")))]
 pub(crate) const LEGACY_RELAY_PATH: &str = "/derp";
 /// The legacy HTTP path under which the relay used to allow latency queries.
 /// We keep this for backwards compatibility.
 #[cfg(feature = "iroh-relay")] // legacy paths only used on server-side for backwards compat
+#[cfg_attr(iroh_docsrs, doc(cfg(feature = "iroh-relay")))]
 pub(crate) const LEGACY_RELAY_PROBE_PATH: &str = "/derp/probe";
 
 /// The HTTP upgrade protocol used for relaying.

iroh-net/src/relay/server.rs

@@ -82,6 +82,7 @@ pub struct ServerConfig<EC: fmt::Debug, EA: fmt::Debug = EC> {
     pub stun: Option<StunConfig>,
     /// Socket to serve metrics on.
     #[cfg(feature = "metrics")]
+    #[cfg_attr(iroh_docsrs, doc(cfg(feature = "metrics")))]
     pub metrics_addr: Option<SocketAddr>,
 }