Rollup merge of #54577 - QuietMisdreavus:docs-for-procs, r=GuillaumeGomez

rustdoc: give proc-macros their own pages

related to #49553 but i don't think it'll fix it

Currently, rustdoc doesn't expose proc-macros all that well. In the source crate, only their definition function is exposed, but when re-exported, they're treated as a macro! This is an awkward situation in all accounts. This PR checks functions to see whether they have any of `#[proc_macro]`, `#[proc_macro_attribute]`, or `#[proc_macro_derive]`, and exposes them as macros instead. In addition, attributes and derives are exposed differently than other macros, getting their own item-type, CSS class, and module heading.

![image](https://user-images.githubusercontent.com/5217170/46044803-6df8da00-c0e1-11e8-8c3b-25d2c3beb55c.png)

Function-like proc-macros are lumped in with `macro_rules!` macros, but they get a different declaration block (i'm open to tweaking this, it's just what i thought of given how function-proc-macros operate):

![image](https://user-images.githubusercontent.com/5217170/46044828-84069a80-c0e1-11e8-9cc4-127e5477c395.png)

Proc-macro attributes and derives get their own pages, with a representative declaration block. Derive macros also show off their helper attributes:

![image](https://user-images.githubusercontent.com/5217170/46094583-ef9f4500-c17f-11e8-8f71-fa0a7895c9f6.png)

![image](https://user-images.githubusercontent.com/5217170/46101529-cab3cd80-c191-11e8-857a-946897750da1.png)

There's one wrinkle which this PR doesn't address, which is why i didn't mark this as fixing the linked issue. Currently, proc-macros don't expose their attributes or source span across crates, so while rustdoc knows they exist, that's about all the information it gets. This leads to an "inlined" macro that has absolutely no docs on it, and no `[src]` link to show you where it was declared.

The way i got around it was to keep proc-macro re-export disabled, since we do get enough information across crates to properly link to the source page:

![image](https://user-images.githubusercontent.com/5217170/46045074-2cb4fa00-c0e2-11e8-81bc-33a8205fbd03.png)

Until we can get a proc-macro's docs (and ideally also its source span) across crates, i believe this is the best way forward.

Author: kennytm

src/librustdoc/clean/inline.rs

@@ -13,7 +13,7 @@
 use std::iter::once;
 
 use syntax::ast;
-use syntax::ext::base::MacroKind;
+use syntax::ext::base::{MacroKind, SyntaxExtension};
 use syntax_pos::Span;
 
 use rustc::hir;
@@ -105,12 +105,12 @@ pub fn try_inline(cx: &DocContext, def: Def, name: ast::Name, visited: &mut FxHa
             record_extern_fqn(cx, did, clean::TypeKind::Const);
             clean::ConstantItem(build_const(cx, did))
         }
-        // FIXME(misdreavus): if attributes/derives come down here we should probably document them
-        // separately
+        // FIXME: proc-macros don't propagate attributes or spans across crates, so they look empty
         Def::Macro(did, MacroKind::Bang) => {
+            let mac = build_macro(cx, did, name);
+            if let clean::MacroItem(..) = mac {
                 record_extern_fqn(cx, did, clean::TypeKind::Macro);
-            if let Some(mac) = build_macro(cx, did, name) {
-                clean::MacroItem(mac)
+                mac
             } else {
                 return None;
             }
@@ -442,14 +442,10 @@ fn build_static(cx: &DocContext, did: DefId, mutable: bool) -> clean::Static {
     }
 }
 
-fn build_macro(cx: &DocContext, did: DefId, name: ast::Name) -> Option<clean::Macro> {
+fn build_macro(cx: &DocContext, did: DefId, name: ast::Name) -> clean::ItemEnum {
     let imported_from = cx.tcx.original_crate_name(did.krate);
-    let def = match cx.cstore.load_macro_untracked(did, cx.sess()) {
-        LoadedMacro::MacroDef(macro_def) => macro_def,
-        // FIXME(jseyfried): document proc macro re-exports
-        LoadedMacro::ProcMacro(..) => return None,
-    };
-
+    match cx.cstore.load_macro_untracked(did, cx.sess()) {
+        LoadedMacro::MacroDef(def) => {
             let matchers: hir::HirVec<Span> = if let ast::ItemKind::MacroDef(ref def) = def.node {
                 let tts: Vec<_> = def.stream().into_trees().collect();
                 tts.chunks(4).map(|arm| arm[0].span()).collect()
@@ -463,11 +459,25 @@ fn build_macro(cx: &DocContext, did: DefId, name: ast::Name) -> Option<clean::Ma
                                      format!("    {} => {{ ... }};\n", span.to_src(cx))
                                  }).collect::<String>());
 
-    Some(clean::Macro {
+            clean::MacroItem(clean::Macro {
                 source,
                 imported_from: Some(imported_from).clean(cx),
             })
         }
+        LoadedMacro::ProcMacro(ext) => {
+            let helpers = match &*ext {
+                &SyntaxExtension::ProcMacroDerive(_, ref syms, ..) => { syms.clean(cx) }
+                _ => Vec::new(),
+            };
+
+            clean::ProcMacroItem(clean::ProcMacro {
+                kind: ext.kind(),
+                helpers,
+            })
+        }
+    }
+
+}
 
 /// A trait's generics clause actually contains all of the predicates for all of
 /// its associated types as well. We specifically move these clauses to the

src/librustdoc/clean/mod.rs

@@ -21,6 +21,7 @@ pub use self::Visibility::{Public, Inherited};
 use rustc_target::spec::abi::Abi;
 use syntax::ast::{self, AttrStyle, Ident};
 use syntax::attr;
+use syntax::ext::base::MacroKind;
 use syntax::source_map::{dummy_spanned, Spanned};
 use syntax::ptr::P;
 use syntax::symbol::keywords::{self, Keyword};
@@ -527,6 +528,7 @@ pub enum ItemEnum {
     /// `type`s from an extern block
     ForeignTypeItem,
     MacroItem(Macro),
+    ProcMacroItem(ProcMacro),
     PrimitiveItem(PrimitiveType),
     AssociatedConstItem(Type, Option<String>),
     AssociatedTypeItem(Vec<GenericBound>, Option<Type>),
@@ -588,6 +590,7 @@ impl Clean<Item> for doctree::Module {
         items.extend(self.traits.iter().map(|x| x.clean(cx)));
         items.extend(self.impls.iter().flat_map(|x| x.clean(cx)));
         items.extend(self.macros.iter().map(|x| x.clean(cx)));
+        items.extend(self.proc_macros.iter().map(|x| x.clean(cx)));
 
         // determine if we should display the inner contents or
         // the outer `mod` item for the source code.
@@ -2189,6 +2192,8 @@ pub enum TypeKind {
     Typedef,
     Foreign,
     Macro,
+    Attr,
+    Derive,
 }
 
 pub trait GetDefId {
@@ -3725,7 +3730,12 @@ pub fn register_def(cx: &DocContext, def: Def) -> DefId {
         Def::Static(i, _) => (i, TypeKind::Static),
         Def::Variant(i) => (cx.tcx.parent_def_id(i).expect("cannot get parent def id"),
                             TypeKind::Enum),
-        Def::Macro(i, _) => (i, TypeKind::Macro),
+        Def::Macro(i, mac_kind) => match mac_kind {
+            MacroKind::Bang => (i, TypeKind::Macro),
+            MacroKind::Attr => (i, TypeKind::Attr),
+            MacroKind::Derive => (i, TypeKind::Derive),
+            MacroKind::ProcMacroStub => unreachable!(),
+        },
         Def::SelfTy(Some(def_id), _) => (def_id, TypeKind::Trait),
         Def::SelfTy(_, Some(impl_def_id)) => {
             return impl_def_id
@@ -3780,6 +3790,30 @@ impl Clean<Item> for doctree::Macro {
     }
 }
 
+#[derive(Clone, RustcEncodable, RustcDecodable, Debug)]
+pub struct ProcMacro {
+    pub kind: MacroKind,
+    pub helpers: Vec<String>,
+}
+
+impl Clean<Item> for doctree::ProcMacro {
+    fn clean(&self, cx: &DocContext) -> Item {
+        Item {
+            name: Some(self.name.clean(cx)),
+            attrs: self.attrs.clean(cx),
+            source: self.whence.clean(cx),
+            visibility: Some(Public),
+            stability: self.stab.clean(cx),
+            deprecation: self.depr.clean(cx),
+            def_id: cx.tcx.hir.local_def_id(self.id),
+            inner: ProcMacroItem(ProcMacro {
+                kind: self.kind,
+                helpers: self.helpers.clean(cx),
+            }),
+        }
+    }
+}
+
 #[derive(Clone, RustcEncodable, RustcDecodable, Debug)]
 pub struct Stability {
     pub level: stability::StabilityLevel,

src/librustdoc/doctree.rs

@@ -15,6 +15,7 @@ pub use self::StructType::*;
 use syntax::ast;
 use syntax::ast::{Name, NodeId};
 use syntax::attr;
+use syntax::ext::base::MacroKind;
 use syntax::ptr::P;
 use syntax::source_map::Spanned;
 use syntax_pos::{self, Span};
@@ -46,6 +47,7 @@ pub struct Module {
     pub impls: Vec<Impl>,
     pub foreigns: Vec<hir::ForeignMod>,
     pub macros: Vec<Macro>,
+    pub proc_macros: Vec<ProcMacro>,
     pub is_crate: bool,
 }
 
@@ -75,6 +77,7 @@ impl Module {
             impls      : Vec::new(),
             foreigns   : Vec::new(),
             macros     : Vec::new(),
+            proc_macros: Vec::new(),
             is_crate   : false,
         }
     }
@@ -264,6 +267,17 @@ pub struct Import {
     pub whence: Span,
 }
 
+pub struct ProcMacro {
+    pub name: Name,
+    pub id: NodeId,
+    pub kind: MacroKind,
+    pub helpers: Vec<Name>,
+    pub attrs: hir::HirVec<ast::Attribute>,
+    pub whence: Span,
+    pub stab: Option<attr::Stability>,
+    pub depr: Option<attr::Deprecation>,
+}
+
 pub fn struct_type_from_def(vdata: &hir::VariantData) -> StructType {
     match *vdata {
         hir::VariantData::Struct(..) => Plain,

src/librustdoc/html/item_type.rs

@@ -11,6 +11,7 @@
 //! Item types.
 
 use std::fmt;
+use syntax::ext::base::MacroKind;
 use clean;
 
 /// Item type. Corresponds to `clean::ItemEnum` variants.
@@ -19,6 +20,11 @@ use clean;
 /// discriminants. JavaScript then is used to decode them into the original value.
 /// Consequently, every change to this type should be synchronized to
 /// the `itemTypes` mapping table in `static/main.js`.
+///
+/// In addition, code in `html::render` uses this enum to generate CSS classes, page prefixes, and
+/// module headings. If you are adding to this enum and want to ensure that the sidebar also prints
+/// a heading, edit the listing in `html/render.rs`, function `sidebar_module`. This uses an
+/// ordering based on a helper function inside `item_module`, in the same file.
 #[derive(Copy, PartialEq, Clone, Debug)]
 pub enum ItemType {
     Module          = 0,
@@ -44,6 +50,8 @@ pub enum ItemType {
     ForeignType     = 20,
     Keyword         = 21,
     Existential     = 22,
+    ProcAttribute   = 23,
+    ProcDerive      = 24,
 }
 
 
@@ -88,6 +96,12 @@ impl<'a> From<&'a clean::Item> for ItemType {
             clean::AssociatedTypeItem(..)  => ItemType::AssociatedType,
             clean::ForeignTypeItem         => ItemType::ForeignType,
             clean::KeywordItem(..)         => ItemType::Keyword,
+            clean::ProcMacroItem(ref mac)  => match mac.kind {
+                MacroKind::Bang            => ItemType::Macro,
+                MacroKind::Attr            => ItemType::ProcAttribute,
+                MacroKind::Derive          => ItemType::ProcDerive,
+                MacroKind::ProcMacroStub   => unreachable!(),
+            }
             clean::StrippedItem(..)        => unreachable!(),
         }
     }
@@ -108,6 +122,8 @@ impl From<clean::TypeKind> for ItemType {
             clean::TypeKind::Typedef  => ItemType::Typedef,
             clean::TypeKind::Foreign  => ItemType::ForeignType,
             clean::TypeKind::Macro    => ItemType::Macro,
+            clean::TypeKind::Attr     => ItemType::ProcAttribute,
+            clean::TypeKind::Derive   => ItemType::ProcDerive,
         }
     }
 }
@@ -138,6 +154,8 @@ impl ItemType {
             ItemType::ForeignType     => "foreigntype",
             ItemType::Keyword         => "keyword",
             ItemType::Existential     => "existential",
+            ItemType::ProcAttribute   => "attr",
+            ItemType::ProcDerive      => "derive",
         }
     }
 
@@ -166,7 +184,9 @@ impl ItemType {
             ItemType::Constant |
             ItemType::AssociatedConst => NameSpace::Value,
 
-            ItemType::Macro => NameSpace::Macro,
+            ItemType::Macro |
+            ItemType::ProcAttribute |
+            ItemType::ProcDerive => NameSpace::Macro,
 
             ItemType::Keyword => NameSpace::Keyword,
         }

src/librustdoc/html/render.rs

@@ -56,6 +56,7 @@ use externalfiles::ExternalHtml;
 
 use serialize::json::{ToJson, Json, as_json};
 use syntax::ast;
+use syntax::ext::base::MacroKind;
 use syntax::source_map::FileName;
 use syntax::feature_gate::UnstableFeatures;
 use rustc::hir::def_id::{CrateNum, CRATE_DEF_INDEX, DefId};
@@ -1595,6 +1596,8 @@ struct AllTypes {
     statics: FxHashSet<ItemEntry>,
     constants: FxHashSet<ItemEntry>,
     keywords: FxHashSet<ItemEntry>,
+    attributes: FxHashSet<ItemEntry>,
+    derives: FxHashSet<ItemEntry>,
 }
 
 impl AllTypes {
@@ -1613,6 +1616,8 @@ impl AllTypes {
             statics: new_set(100),
             constants: new_set(100),
             keywords: new_set(100),
+            attributes: new_set(100),
+            derives: new_set(100),
         }
     }
 
@@ -1634,6 +1639,8 @@ impl AllTypes {
                 ItemType::Existential => self.existentials.insert(ItemEntry::new(new_url, name)),
                 ItemType::Static => self.statics.insert(ItemEntry::new(new_url, name)),
                 ItemType::Constant => self.constants.insert(ItemEntry::new(new_url, name)),
+                ItemType::ProcAttribute => self.attributes.insert(ItemEntry::new(new_url, name)),
+                ItemType::ProcDerive => self.derives.insert(ItemEntry::new(new_url, name)),
                 _ => true,
             };
         }
@@ -1673,6 +1680,8 @@ impl fmt::Display for AllTypes {
         print_entries(f, &self.primitives, "Primitives", "primitives")?;
         print_entries(f, &self.traits, "Traits", "traits")?;
         print_entries(f, &self.macros, "Macros", "macros")?;
+        print_entries(f, &self.attributes, "Attribute Macros", "attributes")?;
+        print_entries(f, &self.derives, "Derive Macros", "derives")?;
         print_entries(f, &self.functions, "Functions", "functions")?;
         print_entries(f, &self.typedefs, "Typedefs", "typedefs")?;
         print_entries(f, &self.existentials, "Existentials", "existentials")?;
@@ -2155,6 +2164,12 @@ impl<'a> fmt::Display for Item<'a> {
             clean::EnumItem(..) => write!(fmt, "Enum ")?,
             clean::TypedefItem(..) => write!(fmt, "Type Definition ")?,
             clean::MacroItem(..) => write!(fmt, "Macro ")?,
+            clean::ProcMacroItem(ref mac) => match mac.kind {
+                MacroKind::Bang => write!(fmt, "Macro ")?,
+                MacroKind::Attr => write!(fmt, "Attribute Macro ")?,
+                MacroKind::Derive => write!(fmt, "Derive Macro ")?,
+                MacroKind::ProcMacroStub => unreachable!(),
+            }
             clean::PrimitiveItem(..) => write!(fmt, "Primitive Type ")?,
             clean::StaticItem(..) | clean::ForeignStaticItem(..) => write!(fmt, "Static ")?,
             clean::ConstantItem(..) => write!(fmt, "Constant ")?,
@@ -2191,6 +2206,7 @@ impl<'a> fmt::Display for Item<'a> {
             clean::EnumItem(ref e) => item_enum(fmt, self.cx, self.item, e),
             clean::TypedefItem(ref t, _) => item_typedef(fmt, self.cx, self.item, t),
             clean::MacroItem(ref m) => item_macro(fmt, self.cx, self.item, m),
+            clean::ProcMacroItem(ref m) => item_proc_macro(fmt, self.cx, self.item, m),
             clean::PrimitiveItem(ref p) => item_primitive(fmt, self.cx, self.item, p),
             clean::StaticItem(ref i) | clean::ForeignStaticItem(ref i) =>
                 item_static(fmt, self.cx, self.item, i),
@@ -4079,11 +4095,12 @@ impl<'a> fmt::Display for Sidebar<'a> {
                 write!(fmt,
                        "<div class='block version'>\
                         <p>Version {}</p>\
-                        </div>
-                        <a id='all-types' href='all.html'><p>See all {}'s items</p></a>",
-                       version,
-                       it.name.as_ref().unwrap())?;
+                        </div>",
+                       version)?;
             }
+
+            write!(fmt, "<a id='all-types' href='all.html'><p>See all {}'s items</p></a>",
+                   it.name.as_ref().expect("crates always have a name"))?;
         }
 
         write!(fmt, "<div class=\"sidebar-elems\">")?;
@@ -4523,6 +4540,8 @@ fn item_ty_to_strs(ty: &ItemType) -> (&'static str, &'static str) {
         ItemType::ForeignType     => ("foreign-types", "Foreign Types"),
         ItemType::Keyword         => ("keywords", "Keywords"),
         ItemType::Existential     => ("existentials", "Existentials"),
+        ItemType::ProcAttribute   => ("attributes", "Attribute Macros"),
+        ItemType::ProcDerive      => ("derives", "Derive Macros"),
     }
 }
 
@@ -4598,6 +4617,39 @@ fn item_macro(w: &mut fmt::Formatter, cx: &Context, it: &clean::Item,
     document(w, cx, it)
 }
 
+fn item_proc_macro(w: &mut fmt::Formatter, cx: &Context, it: &clean::Item, m: &clean::ProcMacro)
+    -> fmt::Result
+{
+    let name = it.name.as_ref().expect("proc-macros always have names");
+    match m.kind {
+        MacroKind::Bang => {
+            write!(w, "<pre class='rust macro'>")?;
+            write!(w, "{}!() {{ /* proc-macro */ }}", name)?;
+            write!(w, "</pre>")?;
+        }
+        MacroKind::Attr => {
+            write!(w, "<pre class='rust attr'>")?;
+            write!(w, "#[{}]", name)?;
+            write!(w, "</pre>")?;
+        }
+        MacroKind::Derive => {
+            write!(w, "<pre class='rust derive'>")?;
+            write!(w, "#[derive({})]", name)?;
+            if !m.helpers.is_empty() {
+                writeln!(w, "\n{{")?;
+                writeln!(w, "    // Attributes available to this derive:")?;
+                for attr in &m.helpers {
+                    writeln!(w, "    #[{}]", attr)?;
+                }
+                write!(w, "}}")?;
+            }
+            write!(w, "</pre>")?;
+        }
+        _ => {}
+    }
+    document(w, cx, it)
+}
+
 fn item_primitive(w: &mut fmt::Formatter, cx: &Context,
                   it: &clean::Item,
                   _p: &clean::PrimitiveType) -> fmt::Result {