Do not document reexports

Author: bugadani

src/lib.rs

@@ -198,6 +198,9 @@ pub fn unstable(args: TokenStream, input: TokenStream) -> TokenStream {
 /// This attribute does not change the visibility of the annotated item. You should ensure that the
 /// item's visibility is set to `pub` if you want it to be part of your crate's public API.
 ///
+/// Re-exports (`pub use`) do not modify the re-exported item's stability or documentation, and they have
+/// no way to display the `since` and `issue` information.
+///
 /// # See also
 ///
 /// - The [`unstable`] attribute for marking an API as unstable.

src/stable.rs

@@ -25,7 +25,7 @@ pub fn stable_macro(args: TokenStream, input: TokenStream) -> TokenStream {
             Item::Trait(item_trait) => unstable_attribute.expand(item_trait),
             Item::Const(item_const) => unstable_attribute.expand(item_const),
             Item::Static(item_static) => unstable_attribute.expand(item_static),
-            Item::Use(item_use) => unstable_attribute.expand(item_use),
+            Item::Use(item_use) => unstable_attribute.expand_use(item_use),
             Item::Impl(item_impl) => unstable_attribute.expand_impl(item_impl),
             _ => panic!("unsupported item type"),
         },
@@ -51,6 +51,13 @@ impl StableAttribute {
         self.expand_impl(item)
     }
 
+    pub fn expand_use(&self, item: impl ItemLike + ToTokens + Clone) -> TokenStream {
+        // We don't want to transform `pub use` items. Adding documentation has adverse effects.
+        // The reexported type can signal its own stability, the reexport itself can really only
+        // use the label that rustdoc renders.
+        item.into_token_stream()
+    }
+
     pub fn expand_impl(&self, mut item: impl Stability + ToTokens) -> TokenStream {
         let doc = if let Some(ref version) = self.since {
             formatdoc! {"
@@ -273,14 +280,13 @@ mod tests {
     }
 
     #[test]
-    fn expand_public_use() {
+    fn public_use_is_noop() {
         let item: syn::ItemUse = parse_quote! {
             pub use crate::foo::bar;
         };
         let stable = StableAttribute::default();
-        let tokens = stable.expand(item);
+        let tokens = stable.expand_use(item);
         let expected = quote! {
-            #[doc = #STABLE_DOC]
             pub use crate::foo::bar;
         };
         assert_eq!(tokens.to_string(), expected.to_string());

src/unstable.rs

@@ -25,7 +25,7 @@ pub fn unstable_macro(args: TokenStream, input: TokenStream) -> TokenStream {
             Item::Trait(item_trait) => unstable_attribute.expand(item_trait),
             Item::Const(item_const) => unstable_attribute.expand(item_const),
             Item::Static(item_static) => unstable_attribute.expand(item_static),
-            Item::Use(item_use) => unstable_attribute.expand(item_use),
+            Item::Use(item_use) => unstable_attribute.expand_use(item_use),
             Item::Impl(item_impl) => unstable_attribute.expand_impl(item_impl),
             _ => panic!("unsupported item type"),
         },
@@ -87,6 +87,25 @@ impl UnstableAttribute {
         }
     }
 
+    pub fn expand_use(&self, item: impl ItemLike + ToTokens + Clone) -> TokenStream {
+        // We don't want to transform `pub use` items. Adding documentation has adverse effects.
+        // The reexported type can signal its own stability, the reexport itself can really only
+        // use the label that rustdoc renders.
+        let feature_flag = self.feature_flag();
+
+        #[cfg(not(instability_disable_unstable_docs))]
+        let cfg_gate_unstable = quote! { #[cfg(any(doc, feature = #feature_flag))] };
+
+        #[cfg(instability_disable_unstable_docs)]
+        let cfg_gate_unstable = quote! { #[cfg(feature = #feature_flag)] };
+
+        quote! {
+            #cfg_gate_unstable
+            #[cfg_attr(docsrs, doc(cfg(feature = #feature_flag)))]
+            #item
+        }
+    }
+
     pub fn expand_impl(&self, mut item: impl Stability + ToTokens) -> TokenStream {
         let feature_flag = self.feature_flag();
         self.add_doc(&mut item);
@@ -400,16 +419,14 @@ mod tests {
         let item: syn::ItemUse = parse_quote! {
             pub use crate::foo::bar;
         };
-        let tokens = UnstableAttribute::default().expand(item);
+        let tokens = UnstableAttribute::default().expand_use(item);
         let expected = quote! {
             #[cfg(any(doc, feature = "unstable"))]
             #[cfg_attr(docsrs, doc(cfg(feature = "unstable")))]
-            #[doc = #DEFAULT_DOC]
             pub use crate::foo::bar;
 
             #[cfg(not(any(doc, feature = "unstable")))]
             #[allow(unused_imports)]
-            #[doc = #DEFAULT_DOC]
             pub(crate) use crate::foo::bar;
         };
         assert_eq!(tokens.to_string(), expected.to_string());
@@ -462,20 +479,18 @@ mod tests {
     }
 
     #[test]
-    fn expand_public_use() {
+    fn expand_public_use_no_docs() {
         let item: syn::ItemUse = parse_quote! {
             pub use crate::foo::bar;
         };
-        let tokens = UnstableAttribute::default().expand(item);
+        let tokens = UnstableAttribute::default().expand_use(item);
         let expected = quote! {
             #[cfg(feature = "unstable")]
             #[cfg_attr(docsrs, doc(cfg(feature = "unstable")))]
-            #[doc = #DEFAULT_DOC]
             pub use crate::foo::bar;
 
             #[cfg(not(feature = "unstable"))]
             #[allow(unused_imports)]
-            #[doc = #DEFAULT_DOC]
             pub(crate) use crate::foo::bar;
         };
         assert_eq!(tokens.to_string(), expected.to_string());