Do not document reexports (#33)

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"),
         },
@@ -53,9 +53,26 @@ impl UnstableAttribute {
             return item.into_token_stream();
         }
 
-        let feature_flag = self.feature_flag();
         self.add_doc(&mut item);
 
+        self.expand_item_without_doc(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.
+        if !item.is_public() {
+            // We only care about public items.
+            return item.into_token_stream();
+        }
+
+        self.expand_item_without_doc(item)
+    }
+
+    fn expand_item_without_doc(&self, item: impl ItemLike + ToTokens + Clone) -> TokenStream {
+        let feature_flag = self.feature_flag();
+
         let mut hidden_item = item.clone();
         hidden_item.set_visibility(parse_quote! { pub(crate) });
 
@@ -400,16 +417,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 +477,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());