docs: enable feature tagging (#2395)

aws · Dec 3, 2024 · 82943e4 · 82943e4
1 parent a5fd516
commit 82943e4
Show file tree

Hide file tree

Showing 5 changed files with 26 additions and 6 deletions.
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -150,17 +150,18 @@ jobs:
         with:
           submodules: true
 
-      - name: Install rust toolchain
-        id: toolchain
+      # nightly docrs features are used
+      - name: Install rust nightly toolchain
+        id: nightly-toolchain
         run: |
-          rustup toolchain install stable --profile minimal
-          rustup override set stable
-
+          rustup toolchain install nightly --profile minimal
 
       - uses: camshaft/rust-cache@v1
 
       - name: Run cargo doc
-        run: cargo doc --all-features --no-deps --workspace --exclude s2n-quic-qns
+        run: cargo +nightly doc --all-features --no-deps --workspace --exclude s2n-quic-qns
+        env:
+          RUSTDOCFLAGS: --cfg docsrs
 
       - uses: aws-actions/configure-aws-credentials@v4.0.2
         if: github.event_name == 'push' || github.repository == github.event.pull_request.head.repo.full_name

diff --git a/quic/s2n-quic/src/lib.rs b/quic/s2n-quic/src/lib.rs
@@ -103,6 +103,16 @@
 //! [s2n-tls]: https://github.com/aws/s2n-tls
 //! [rustls]: https://github.com/rustls/rustls
 
+// Tag docs with the required platform and features.
+// https://doc.rust-lang.org/rustdoc/unstable-features.html
+#![cfg_attr(docsrs, feature(doc_cfg))]
+#![cfg_attr(
+    docsrs,
+    feature(doc_auto_cfg),
+    feature(doc_cfg_hide),
+    doc(cfg_hide(doc))
+)]
+
 #[macro_use]
 pub mod provider;
 

diff --git a/quic/s2n-quic/src/provider.rs b/quic/s2n-quic/src/provider.rs
@@ -26,6 +26,7 @@ pub(crate) mod sync;
 
 cfg_if!(
     if #[cfg(any(test, feature = "unstable-provider-connection-close-formatter"))] {
+        #[cfg_attr(docsrs, doc(cfg(feature = "unstable-provider-connection-close-formatter")))]
         pub mod connection_close_formatter;
     } else {
         #[allow(dead_code)]
@@ -35,6 +36,7 @@ cfg_if!(
 
 cfg_if!(
     if #[cfg(any(test, feature = "unstable-provider-packet-interceptor"))] {
+        #[cfg_attr(docsrs, doc(cfg(feature = "unstable-provider-packet-interceptor")))]
         pub mod packet_interceptor;
     } else {
         #[allow(dead_code)]
@@ -44,6 +46,7 @@ cfg_if!(
 
 cfg_if!(
     if #[cfg(any(test, feature = "unstable-provider-random"))] {
+        #[cfg_attr(docsrs, doc(cfg(feature = "unstable-provider-random")))]
         pub mod random;
     } else {
         #[allow(dead_code)]
@@ -53,6 +56,7 @@ cfg_if!(
 
 cfg_if!(
     if #[cfg(any(test, feature = "unstable-provider-datagram"))] {
+        #[cfg_attr(docsrs, doc(cfg(feature = "unstable-provider-datagram")))]
         pub mod datagram;
     } else {
         #[allow(dead_code)]
@@ -62,6 +66,7 @@ cfg_if!(
 
 cfg_if!(
     if #[cfg(any(test, feature = "unstable-provider-dc"))] {
+        #[cfg_attr(docsrs, doc(cfg(feature = "unstable-provider-dc")))]
         pub mod dc;
     } else {
         #[allow(dead_code)]

diff --git a/quic/s2n-quic/src/provider/congestion_controller.rs b/quic/s2n-quic/src/provider/congestion_controller.rs
@@ -14,6 +14,7 @@ pub trait Provider {
 
 cfg_if! {
     if #[cfg(feature = "unstable-congestion-controller")] {
+        #[cfg_attr(docsrs, doc(cfg(feature = "unstable-congestion-controller")))]
         // Export the types needed to implement the CongestionController trait
         pub use s2n_quic_core::{
             random::Generator as RandomGenerator,

diff --git a/quic/s2n-quic/src/provider/tls.rs b/quic/s2n-quic/src/provider/tls.rs
@@ -22,6 +22,7 @@ impl_provider_utils!();
 
 cfg_if! {
     if #[cfg(feature = "provider-tls-default")] {
+        #[cfg_attr(docsrs, doc(cfg(feature = "provider-tls-default")))]
         pub mod default {
             //! Provides the recommended implementation of TLS using platform detection
             pub use super::default_tls::*;
@@ -238,6 +239,7 @@ mod default_tls {
     // TODO stub out default that fails with error when started
 }
 
+#[cfg_attr(docsrs, doc(cfg(feature = "provider-tls-rustls")))]
 #[cfg(feature = "s2n-quic-rustls")]
 pub mod rustls {
     //! Provides the [rustls](https://docs.rs/rustls/) implementation of TLS
@@ -273,6 +275,7 @@ pub mod rustls {
     }
 }
 
+#[cfg_attr(docsrs, doc(cfg(feature = "provider-tls-s2n")))]
 #[cfg(feature = "s2n-quic-tls")]
 pub mod s2n_tls {
     //! Provides the [s2n-tls](https://github.com/aws/s2n-tls) implementation of TLS