Improve documentation generation (#554)

Make `x86_64-unknown-linux-gnu` the default target, as it's more feature rich. Users may not realize that they can select their platform on docs.rs, so it's better to show them more extensive documentation. Don't pass `--cfg docsrs` to rustdoc for docs.rs builds, it's already passed by docs.rs. Generate documentation about supported platforms automatically from the `cfg` attributes.
rust-lang · Feb 18, 2025 · 62479f7 · 62479f7
1 parent 23f7a86
commit 62479f7
Show file tree

Hide file tree

Showing 6 changed files with 19 additions and 570 deletions.
diff --git a/Cargo.toml b/Cargo.toml
@@ -29,8 +29,23 @@ include       = [
 
 [package.metadata.docs.rs]
 all-features = true
-rustdoc-args = ["--cfg", "docsrs"]
-targets = ["aarch64-apple-ios", "aarch64-linux-android", "x86_64-apple-darwin", "x86_64-unknown-fuchsia", "x86_64-pc-windows-msvc", "x86_64-pc-solaris", "x86_64-unknown-freebsd", "x86_64-unknown-illumos", "x86_64-unknown-linux-gnu", "x86_64-unknown-linux-musl", "x86_64-unknown-netbsd", "x86_64-unknown-redox", "armv7-linux-androideabi", "i686-linux-android"]
+default-target = "x86_64-unknown-linux-gnu"
+targets = [
+  "aarch64-apple-ios",
+  "aarch64-linux-android",
+  "armv7-linux-androideabi",
+  "i686-linux-android",
+  "x86_64-apple-darwin",
+  "x86_64-pc-solaris",
+  "x86_64-pc-windows-msvc",
+  "x86_64-unknown-freebsd",
+  "x86_64-unknown-fuchsia",
+  "x86_64-unknown-illumos",
+  "x86_64-unknown-linux-gnu",
+  "x86_64-unknown-linux-musl",
+  "x86_64-unknown-netbsd",
+  "x86_64-unknown-redox",
+]
 
 [package.metadata.playground]
 features = ["all"]

diff --git a/src/lib.rs b/src/lib.rs
@@ -51,8 +51,8 @@
 //! that are not available on all OSs.
 
 #![deny(missing_docs, missing_debug_implementations, rust_2018_idioms)]
-// Show required OS/features on docs.rs.
-#![cfg_attr(docsrs, feature(doc_cfg))]
+// Automatically generate required OS/features for docs.rs.
+#![cfg_attr(docsrs, feature(doc_auto_cfg))]
 // Disallow warnings when running tests.
 #![cfg_attr(test, deny(warnings))]
 // Disallow warnings in examples.
@@ -266,20 +266,14 @@ impl Type {
     ///
     /// Used for the DCCP protocol.
     #[cfg(all(feature = "all", target_os = "linux"))]
-    #[cfg_attr(docsrs, doc(cfg(all(feature = "all", target_os = "linux"))))]
     pub const DCCP: Type = Type(sys::SOCK_DCCP);
 
     /// Type corresponding to `SOCK_SEQPACKET`.
     #[cfg(all(feature = "all", not(target_os = "espidf")))]
-    #[cfg_attr(docsrs, doc(cfg(all(feature = "all", not(target_os = "espidf")))))]
     pub const SEQPACKET: Type = Type(sys::SOCK_SEQPACKET);
 
     /// Type corresponding to `SOCK_RAW`.
     #[cfg(all(feature = "all", not(any(target_os = "redox", target_os = "espidf"))))]
-    #[cfg_attr(
-        docsrs,
-        doc(cfg(all(feature = "all", not(any(target_os = "redox", target_os = "espidf")))))
-    )]
     pub const RAW: Type = Type(sys::SOCK_RAW);
 }
 
@@ -324,7 +318,6 @@ impl Protocol {
 
     /// Protocol corresponding to `DCCP`.
     #[cfg(all(feature = "all", target_os = "linux"))]
-    #[cfg_attr(docsrs, doc(cfg(all(feature = "all", target_os = "linux"))))]
     pub const DCCP: Protocol = Protocol(sys::IPPROTO_DCCP);
 
     /// Protocol corresponding to `SCTP`.
@@ -364,7 +357,6 @@ impl From<Protocol> for c_int {
 ///
 /// Flags provide additional information about incoming messages.
 #[cfg(not(target_os = "redox"))]
-#[cfg_attr(docsrs, doc(cfg(not(target_os = "redox"))))]
 #[derive(Copy, Clone, Eq, PartialEq)]
 pub struct RecvFlags(c_int);
 
@@ -523,24 +515,6 @@ impl TcpKeepalive {
         target_os = "watchos",
         target_os = "windows",
     ))]
-    #[cfg_attr(
-        docsrs,
-        doc(cfg(any(
-            target_os = "android",
-            target_os = "dragonfly",
-            target_os = "freebsd",
-            target_os = "fuchsia",
-            target_os = "illumos",
-            target_os = "ios",
-            target_os = "visionos",
-            target_os = "linux",
-            target_os = "macos",
-            target_os = "netbsd",
-            target_os = "tvos",
-            target_os = "watchos",
-            target_os = "windows",
-        )))
-    )]
     pub const fn with_interval(self, interval: Duration) -> Self {
         Self {
             interval: Some(interval),
@@ -569,26 +543,6 @@ impl TcpKeepalive {
             target_os = "watchos",
         )
     ))]
-    #[cfg_attr(
-        docsrs,
-        doc(cfg(all(
-            feature = "all",
-            any(
-                target_os = "android",
-                target_os = "dragonfly",
-                target_os = "freebsd",
-                target_os = "fuchsia",
-                target_os = "illumos",
-                target_os = "ios",
-                target_os = "visionos",
-                target_os = "linux",
-                target_os = "macos",
-                target_os = "netbsd",
-                target_os = "tvos",
-                target_os = "watchos",
-            )
-        )))
-    )]
     pub const fn with_retries(self, retries: u32) -> Self {
         Self {
             retries: Some(retries),