docs(*): Use doc-auto-cfg feature (#3029)

## Description

This switches from the doc-cfg feature which needs an explicit
annotation to the doc-auto-cfg feature which does not need this.  We
already had several places where the docs and actual features were out
of sync.  So hopefully this will work better.

doc-auto-cfg does not seem perfect and may miss some things.  E.g. one
difference I noticed is that it does not seem to surface the "test"
feature when we do `any(test, feature = "something")`.  But I'm
thinking that might be a reasonable price to pay here.

## Breaking Changes

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

## Notes & open questions

<!-- Any notes, remarks or open questions you have to make about the PR.
-->

## 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.

Cargo.toml

@@ -30,13 +30,13 @@ incremental = false
 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
+# is available.  To preview this locally use: RUSTDOCFLAGS="--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.
+# feature(doc_auto_cfg))]` in the crate.
 unexpected_cfgs = { level = "warn", check-cfg = ["cfg(iroh_docsrs)"] }
 
 [workspace.lints.clippy]

iroh-base/src/hash.rs

@@ -230,7 +230,6 @@ pub struct HashAndFormat {
 }
 
 #[cfg(feature = "redb")]
-#[cfg_attr(iroh_docsrs, cfg(feature = "redb"))]
 mod redb_support {
     use postcard::experimental::max_size::MaxSize;
     use redb::{Key as RedbKey, Value as RedbValue};

iroh-base/src/lib.rs

@@ -1,23 +1,17 @@
 //! Base types and utilities for Iroh
-#![cfg_attr(iroh_docsrs, feature(doc_cfg))]
+#![cfg_attr(iroh_docsrs, feature(doc_auto_cfg))]
 
 #[cfg(feature = "base32")]
-#[cfg_attr(iroh_docsrs, doc(cfg(feature = "base32")))]
 pub mod base32;
 #[cfg(feature = "hash")]
-#[cfg_attr(iroh_docsrs, doc(cfg(feature = "hash")))]
 pub mod hash;
 #[cfg(feature = "key")]
-#[cfg_attr(iroh_docsrs, doc(cfg(feature = "key")))]
 pub mod key;
 #[cfg(feature = "key")]
-#[cfg_attr(iroh_docsrs, doc(cfg(feature = "key")))]
 pub mod node_addr;
 #[cfg(feature = "relay")]
-#[cfg_attr(iroh_docsrs, doc(cfg(feature = "relay")))]
 pub mod relay_map;
 #[cfg(any(feature = "relay", feature = "key"))]
 mod relay_url;
 #[cfg(feature = "base32")]
-#[cfg_attr(iroh_docsrs, doc(cfg(feature = "base32")))]
 pub mod ticket;

iroh-base/src/ticket.rs

@@ -1,13 +1,10 @@
 use crate::base32;
 
 #[cfg(feature = "key")]
-#[cfg_attr(iroh_docsrs, doc(cfg(feature = "key")))]
 mod blob;
 #[cfg(feature = "key")]
-#[cfg_attr(iroh_docsrs, doc(cfg(feature = "key")))]
 mod node;
 #[cfg(feature = "key")]
-#[cfg_attr(iroh_docsrs, doc(cfg(feature = "key")))]
 pub use self::{blob::BlobTicket, node::NodeTicket};
 
 /// A ticket is a serializable object combining information required for an operation.

iroh-relay/src/client.rs

@@ -203,7 +203,6 @@ 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>,
@@ -269,7 +268,6 @@ 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
@@ -1093,7 +1091,6 @@ impl DnsExt for DnsResolver {
 
 /// 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-relay/src/defaults.rs

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

iroh-relay/src/http.rs

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

iroh-relay/src/lib.rs

@@ -26,7 +26,7 @@
 //!   STUN support and expose metrics.
 // Based on tailscale/derp/derp.go
 
-#![cfg_attr(iroh_docsrs, feature(doc_cfg))]
+#![cfg_attr(iroh_docsrs, feature(doc_auto_cfg))]
 #![deny(missing_docs, rustdoc::broken_intra_doc_links)]
 
 pub mod client;
@@ -35,7 +35,6 @@ pub mod http;
 pub mod protos;
 pub mod quic;
 #[cfg(feature = "server")]
-#[cfg_attr(iroh_docsrs, doc(cfg(feature = "server")))]
 pub mod server;
 
 #[cfg(test)]

iroh-relay/src/protos/relay.rs

@@ -39,11 +39,9 @@ const MAX_FRAME_SIZE: usize = 1024 * 1024;
 const MAGIC: &str = "RELAY🔑";
 
 #[cfg(feature = "server")]
-#[cfg_attr(iroh_docsrs, doc(cfg(feature = "server")))]
 pub(crate) const KEEP_ALIVE: Duration = Duration::from_secs(60);
 // TODO: what should this be?
 #[cfg(feature = "server")]
-#[cfg_attr(iroh_docsrs, doc(cfg(feature = "server")))]
 pub(crate) const SERVER_CHANNEL_SIZE: usize = 1024 * 100;
 /// The number of packets buffered for sending per client
 pub(crate) const PER_CLIENT_SEND_QUEUE_DEPTH: usize = 512; //32;
@@ -170,7 +168,6 @@ 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(any(test, feature = "server"))]
-#[cfg_attr(iroh_docsrs, doc(cfg(feature = "server")))]
 pub(crate) async fn recv_client_key<S: Stream<Item = anyhow::Result<Frame>> + Unpin>(
     stream: S,
 ) -> anyhow::Result<(PublicKey, ClientInfo)> {
@@ -289,7 +286,6 @@ impl Frame {
 
     /// Serialized length with frame header.
     #[cfg(feature = "server")]
-    #[cfg_attr(iroh_docsrs, doc(cfg(feature = "server")))]
     pub(crate) fn len_with_header(&self) -> usize {
         self.len() + HEADER_LEN
     }
@@ -553,7 +549,6 @@ 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(any(test, feature = "server"))]
-#[cfg_attr(iroh_docsrs, doc(cfg(feature = "server")))]
 pub(crate) async fn recv_frame<S: Stream<Item = anyhow::Result<Frame>> + Unpin>(
     frame_type: FrameType,
     mut stream: S,

iroh-relay/src/quic.rs

@@ -13,7 +13,6 @@ pub const QUIC_ADDR_DISC_CLOSE_CODE: VarInt = VarInt::from_u32(1);
 pub const QUIC_ADDR_DISC_CLOSE_REASON: &[u8] = b"finished";
 
 #[cfg(feature = "server")]
-#[cfg_attr(iroh_docsrs, doc(cfg(feature = "server")))]
 pub(crate) mod server {
     use quinn::{crypto::rustls::QuicServerConfig, ApplicationClose};
     use tokio::task::JoinSet;

iroh-relay/src/server.rs

@@ -48,7 +48,6 @@ mod http_server;
 mod metrics;
 pub(crate) mod streams;
 #[cfg(feature = "test-utils")]
-#[cfg_attr(iroh_docsrs, doc(cfg(feature = "test-utils")))]
 pub mod testing;
 
 pub use self::{
@@ -94,7 +93,6 @@ pub struct ServerConfig<EC: fmt::Debug, EA: fmt::Debug = EC> {
     pub quic: Option<QuicConfig>,
     /// Socket to serve metrics on.
     #[cfg(feature = "metrics")]
-    #[cfg_attr(iroh_docsrs, doc(cfg(feature = "metrics")))]
     pub metrics_addr: Option<SocketAddr>,
 }
 
@@ -448,7 +446,6 @@ impl Server {
     ///
     /// This uses [`Self::https_addr`] so it's mostly useful for local development.
     #[cfg(feature = "test-utils")]
-    #[cfg_attr(iroh_docsrs, doc(cfg(feature = "test-utils")))]
     pub fn https_url(&self) -> Option<RelayUrl> {
         self.https_addr.map(|addr| {
             url::Url::parse(&format!("https://{addr}"))
@@ -461,7 +458,6 @@ impl Server {
     ///
     /// This uses [`Self::http_addr`] so it's mostly useful for local development.
     #[cfg(feature = "test-utils")]
-    #[cfg_attr(iroh_docsrs, doc(cfg(feature = "test-utils")))]
     pub fn http_url(&self) -> Option<RelayUrl> {
         self.http_addr.map(|addr| {
             url::Url::parse(&format!("http://{addr}"))

iroh/src/discovery.rs

@@ -125,7 +125,6 @@ use crate::{AddrInfo, Endpoint, NodeId};
 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;
 pub mod static_provider;

iroh/src/discovery/pkarr.rs

@@ -66,7 +66,6 @@ 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/src/endpoint.rs

@@ -96,7 +96,6 @@ 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>,
@@ -307,7 +306,6 @@ impl Builder {
     }
 
     #[cfg(feature = "discovery-pkarr-dht")]
-    #[cfg_attr(iroh_docsrs, doc(cfg(feature = "discovery-pkarr-dht")))]
     /// Configures the endpoint to also use the mainline DHT with default settings.
     ///
     /// This is equivalent to adding a [`crate::discovery::pkarr::dht::DhtDiscovery`]
@@ -328,7 +326,6 @@ impl Builder {
     }
 
     #[cfg(feature = "discovery-local-network")]
-    #[cfg_attr(iroh_docsrs, doc(cfg(feature = "discovery-local-network")))]
     /// Configures the endpoint to also use local network discovery.
     ///
     /// This is equivalent to adding a [`crate::discovery::local_swarm_discovery::LocalSwarmDiscovery`]
@@ -412,7 +409,6 @@ 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
@@ -1379,7 +1375,6 @@ impl RelayMode {
 }
 
 /// Environment variable to force the use of staging relays.
-#[cfg_attr(iroh_docsrs, doc(cfg(not(test))))]
 pub const ENV_FORCE_STAGING_RELAYS: &str = "IROH_FORCE_STAGING_RELAYS";
 
 /// Returns `true` if the use of staging relays is forced.

iroh/src/lib.rs

@@ -231,7 +231,7 @@
 
 #![recursion_limit = "256"]
 #![deny(missing_docs, rustdoc::broken_intra_doc_links)]
-#![cfg_attr(iroh_docsrs, feature(doc_cfg))]
+#![cfg_attr(iroh_docsrs, feature(doc_auto_cfg))]
 
 pub mod defaults;
 mod disco;
@@ -255,5 +255,4 @@ pub use iroh_base::{
 pub use iroh_relay as relay;
 
 #[cfg(any(test, feature = "test-utils"))]
-#[cfg_attr(iroh_docsrs, doc(cfg(any(test, feature = "test-utils"))))]
 pub mod test_utils;

iroh/src/magicsock.rs

@@ -127,7 +127,6 @@ 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,
 }
 
@@ -249,7 +248,6 @@ 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/src/metrics.rs

@@ -1,6 +1,5 @@
 //! Co-locating all of the iroh metrics structs
 #[cfg(feature = "test-utils")]
-#[cfg_attr(iroh_docsrs, doc(cfg(feature = "test-utils")))]
 pub use iroh_relay::server::Metrics as RelayMetrics;
 pub use net_report::Metrics as NetReportMetrics;
 pub use portmapper::Metrics as PortmapMetrics;