bjoernager/rust
bjoernager/rust
1
Fork 0
Code Activity

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

Browse source 
rustdoc: give proc-macros their own pages

related to https://github.com/rust-lang/rust/issues/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.
This commit is contained in:
kennytm 2018-09-29 16:46:30 +08:00
commit def5f84fa6
No known key found for this signature in database
GPG key ID: FEF6C8051D0E013C
13 changed files with 372 additions and 50 deletions
Download patch file Download diff file Expand all files Collapse all files

64
src/librustdoc/clean/inline.rs
View file

@ -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) => {
record_extern_fqn(cx, did, clean::TypeKind::Macro);
if let Some(mac) = build_macro(cx, did, name) {
clean::MacroItem(mac)
let mac = build_macro(cx, did, name);
if let clean::MacroItem(..) = mac {
record_extern_fqn(cx, did, clean::TypeKind::Macro);
mac
} else {
return None;
}
@ -442,31 +442,41 @@ 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()
} else {
unreachable!()
};
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()
} else {
unreachable!()
};
let source = format!("macro_rules! {} {{\n{}}}",
name.clean(cx),
matchers.iter().map(|span| {
format!(" {} => {{ ... }};\n", span.to_src(cx))
}).collect::<String>());
let source = format!("macro_rules! {} {{\n{}}}",
name.clean(cx),
matchers.iter().map(|span| {
format!(" {} => {{ ... }};\n", span.to_src(cx))
}).collect::<String>());
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,
})
}
}
Some(clean::Macro {
source,
imported_from: Some(imported_from).clean(cx),
})
}
/// A trait's generics clause actually contains all of the predicates for all of

36
src/librustdoc/clean/mod.rs
View file

@ -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,