diff options
Diffstat (limited to 'src/librustdoc/clean/mod.rs')
| -rw-r--r-- | src/librustdoc/clean/mod.rs | 319 |
1 files changed, 268 insertions, 51 deletions
diff --git a/src/librustdoc/clean/mod.rs b/src/librustdoc/clean/mod.rs index c9afa3646b2..be7bd3d5510 100644 --- a/src/librustdoc/clean/mod.rs +++ b/src/librustdoc/clean/mod.rs @@ -44,6 +44,7 @@ use rustc::hir; use rustc_const_math::ConstInt; use std::{mem, slice, vec}; +use std::iter::FromIterator; use std::path::PathBuf; use std::rc::Rc; use std::sync::Arc; @@ -112,6 +113,7 @@ impl<T: Clean<U>, U> Clean<Vec<U>> for P<[T]> { #[derive(Clone, Debug)] pub struct Crate { pub name: String, + pub version: Option<String>, pub src: PathBuf, pub module: Option<Item>, pub externs: Vec<(CrateNum, ExternalCrate)>, @@ -150,7 +152,7 @@ impl<'a, 'tcx> Clean<Crate> for visit_ast::RustdocVisitor<'a, 'tcx> { match module.inner { ModuleItem(ref module) => { for it in &module.items { - if it.is_extern_crate() && it.attrs.has_doc_masked() { + if it.is_extern_crate() && it.attrs.has_doc_flag("masked") { masked_crates.insert(it.def_id.krate); } } @@ -183,6 +185,7 @@ impl<'a, 'tcx> Clean<Crate> for visit_ast::RustdocVisitor<'a, 'tcx> { Crate { name, + version: None, src, module: Some(module), externs, @@ -236,6 +239,7 @@ impl Clean<ExternalCrate> for CrateNum { if prim.is_some() { break; } + // FIXME: should warn on unknown primitives? } } } @@ -297,6 +301,11 @@ impl Item { pub fn doc_value<'a>(&'a self) -> Option<&'a str> { self.attrs.doc_value() } + /// Finds all `doc` attributes as NameValues and returns their corresponding values, joined + /// with newlines. + pub fn collapsed_doc_value(&self) -> Option<String> { + self.attrs.collapsed_doc_value() + } pub fn is_crate(&self) -> bool { match self.inner { StrippedItem(box ModuleItem(Module { is_crate: true, ..})) | @@ -416,11 +425,13 @@ pub enum ItemEnum { ForeignFunctionItem(Function), /// `static`s from an extern block ForeignStaticItem(Static), + /// `type`s from an extern block + ForeignTypeItem, MacroItem(Macro), PrimitiveItem(PrimitiveType), AssociatedConstItem(Type, Option<String>), AssociatedTypeItem(Vec<TyParamBound>, Option<Type>), - DefaultImplItem(DefaultImpl), + AutoImplItem(AutoImpl), /// An item that has been stripped by a rustdoc pass StrippedItem(Box<ItemEnum>), } @@ -559,9 +570,69 @@ impl<I: IntoIterator<Item=ast::NestedMetaItem>> NestedAttributesExt for I { } } +/// A portion of documentation, extracted from a `#[doc]` attribute. +/// +/// Each variant contains the line number within the complete doc-comment where the fragment +/// starts, as well as the Span where the corresponding doc comment or attribute is located. +/// +/// Included files are kept separate from inline doc comments so that proper line-number +/// information can be given when a doctest fails. Sugared doc comments and "raw" doc comments are +/// kept separate because of issue #42760. +#[derive(Clone, RustcEncodable, RustcDecodable, PartialEq, Debug)] +pub enum DocFragment { + // FIXME #44229 (misdreavus): sugared and raw doc comments can be brought back together once + // hoedown is completely removed from rustdoc. + /// A doc fragment created from a `///` or `//!` doc comment. + SugaredDoc(usize, syntax_pos::Span, String), + /// A doc fragment created from a "raw" `#[doc=""]` attribute. + RawDoc(usize, syntax_pos::Span, String), + /// A doc fragment created from a `#[doc(include="filename")]` attribute. Contains both the + /// given filename and the file contents. + Include(usize, syntax_pos::Span, String, String), +} + +impl DocFragment { + pub fn as_str(&self) -> &str { + match *self { + DocFragment::SugaredDoc(_, _, ref s) => &s[..], + DocFragment::RawDoc(_, _, ref s) => &s[..], + DocFragment::Include(_, _, _, ref s) => &s[..], + } + } + + pub fn span(&self) -> syntax_pos::Span { + match *self { + DocFragment::SugaredDoc(_, span, _) | + DocFragment::RawDoc(_, span, _) | + DocFragment::Include(_, span, _, _) => span, + } + } +} + +impl<'a> FromIterator<&'a DocFragment> for String { + fn from_iter<T>(iter: T) -> Self + where + T: IntoIterator<Item = &'a DocFragment> + { + iter.into_iter().fold(String::new(), |mut acc, frag| { + if !acc.is_empty() { + acc.push('\n'); + } + match *frag { + DocFragment::SugaredDoc(_, _, ref docs) + | DocFragment::RawDoc(_, _, ref docs) + | DocFragment::Include(_, _, _, ref docs) => + acc.push_str(docs), + } + + acc + }) + } +} + #[derive(Clone, RustcEncodable, RustcDecodable, PartialEq, Debug, Default)] pub struct Attributes { - pub doc_strings: Vec<String>, + pub doc_strings: Vec<DocFragment>, pub other_attrs: Vec<ast::Attribute>, pub cfg: Option<Rc<Cfg>>, pub span: Option<syntax_pos::Span>, @@ -591,12 +662,53 @@ impl Attributes { None } - pub fn has_doc_masked(&self) -> bool { + /// Reads a `MetaItem` from within an attribute, looks for whether it is a + /// `#[doc(include="file")]`, and returns the filename and contents of the file as loaded from + /// its expansion. + fn extract_include(mi: &ast::MetaItem) + -> Option<(String, String)> + { + mi.meta_item_list().and_then(|list| { + for meta in list { + if meta.check_name("include") { + // the actual compiled `#[doc(include="filename")]` gets expanded to + // `#[doc(include(file="filename", contents="file contents")]` so we need to + // look for that instead + return meta.meta_item_list().and_then(|list| { + let mut filename: Option<String> = None; + let mut contents: Option<String> = None; + + for it in list { + if it.check_name("file") { + if let Some(name) = it.value_str() { + filename = Some(name.to_string()); + } + } else if it.check_name("contents") { + if let Some(docs) = it.value_str() { + contents = Some(docs.to_string()); + } + } + } + + if let (Some(filename), Some(contents)) = (filename, contents) { + Some((filename, contents)) + } else { + None + } + }); + } + } + + None + }) + } + + pub fn has_doc_flag(&self, flag: &str) -> bool { for attr in &self.other_attrs { if !attr.check_name("doc") { continue; } if let Some(items) = attr.meta_item_list() { - if items.iter().filter_map(|i| i.meta_item()).any(|it| it.check_name("masked")) { + if items.iter().filter_map(|i| i.meta_item()).any(|it| it.check_name(flag)) { return true; } } @@ -605,10 +717,12 @@ impl Attributes { false } - pub fn from_ast(diagnostic: &::errors::Handler, attrs: &[ast::Attribute]) -> Attributes { + pub fn from_ast(diagnostic: &::errors::Handler, + attrs: &[ast::Attribute]) -> Attributes { let mut doc_strings = vec![]; let mut sp = None; let mut cfg = Cfg::True; + let mut doc_line = 0; let other_attrs = attrs.iter().filter_map(|attr| { attr.with_desugared_doc(|attr| { @@ -616,7 +730,16 @@ impl Attributes { if let Some(mi) = attr.meta() { if let Some(value) = mi.value_str() { // Extracted #[doc = "..."] - doc_strings.push(value.to_string()); + let value = value.to_string(); + let line = doc_line; + doc_line += value.lines().count(); + + if attr.is_sugared_doc { + doc_strings.push(DocFragment::SugaredDoc(line, attr.span, value)); + } else { + doc_strings.push(DocFragment::RawDoc(line, attr.span, value)); + } + if sp.is_none() { sp = Some(attr.span); } @@ -628,6 +751,14 @@ impl Attributes { Err(e) => diagnostic.span_err(e.span, e.msg), } return None; + } else if let Some((filename, contents)) = Attributes::extract_include(&mi) + { + let line = doc_line; + doc_line += contents.lines().count(); + doc_strings.push(DocFragment::Include(line, + attr.span, + filename, + contents)); } } } @@ -645,7 +776,17 @@ impl Attributes { /// Finds the `doc` attribute as a NameValue and returns the corresponding /// value found. pub fn doc_value<'a>(&'a self) -> Option<&'a str> { - self.doc_strings.first().map(|s| &s[..]) + self.doc_strings.first().map(|s| s.as_str()) + } + + /// Finds all `doc` attributes as NameValues and returns their corresponding values, joined + /// with newlines. + pub fn collapsed_doc_value(&self) -> Option<String> { + if !self.doc_strings.is_empty() { + Some(self.doc_strings.iter().collect()) + } else { + None + } } } @@ -867,8 +1008,8 @@ impl Clean<Lifetime> for hir::Lifetime { let hir_id = cx.tcx.hir.node_to_hir_id(self.id); let def = cx.tcx.named_region(hir_id); match def { - Some(rl::Region::EarlyBound(_, node_id)) | - Some(rl::Region::LateBound(_, node_id)) | + Some(rl::Region::EarlyBound(_, node_id, _)) | + Some(rl::Region::LateBound(_, node_id, _)) | Some(rl::Region::Free(_, node_id)) => { if let Some(lt) = cx.lt_substs.borrow().get(&node_id).cloned() { return lt; @@ -1138,13 +1279,13 @@ pub struct Method { pub abi: Abi, } -impl<'a> Clean<Method> for (&'a hir::MethodSig, hir::BodyId) { +impl<'a> Clean<Method> for (&'a hir::MethodSig, &'a hir::Generics, hir::BodyId) { fn clean(&self, cx: &DocContext) -> Method { Method { - generics: self.0.generics.clean(cx), + generics: self.1.clean(cx), unsafety: self.0.unsafety, constness: self.0.constness, - decl: (&*self.0.decl, self.1).clean(cx), + decl: (&*self.0.decl, self.2).clean(cx), abi: self.0.abi } } @@ -1326,19 +1467,31 @@ impl Clean<FunctionRetTy> for hir::FunctionRetTy { } } +impl GetDefId for FunctionRetTy { + fn def_id(&self) -> Option<DefId> { + match *self { + Return(ref ty) => ty.def_id(), + DefaultReturn => None, + } + } +} + #[derive(Clone, RustcEncodable, RustcDecodable, Debug)] pub struct Trait { pub unsafety: hir::Unsafety, pub items: Vec<Item>, pub generics: Generics, pub bounds: Vec<TyParamBound>, + pub is_spotlight: bool, } impl Clean<Item> for doctree::Trait { fn clean(&self, cx: &DocContext) -> Item { + let attrs = self.attrs.clean(cx); + let is_spotlight = attrs.has_doc_flag("spotlight"); Item { name: Some(self.name.clean(cx)), - attrs: self.attrs.clean(cx), + attrs: attrs, source: self.whence.clean(cx), def_id: cx.tcx.hir.local_def_id(self.id), visibility: self.vis.clean(cx), @@ -1349,6 +1502,7 @@ impl Clean<Item> for doctree::Trait { items: self.items.clean(cx), generics: self.generics.clean(cx), bounds: self.bounds.clean(cx), + is_spotlight: is_spotlight, }), } } @@ -1377,13 +1531,13 @@ impl Clean<Item> for hir::TraitItem { default.map(|e| print_const_expr(cx, e))) } hir::TraitItemKind::Method(ref sig, hir::TraitMethod::Provided(body)) => { - MethodItem((sig, body).clean(cx)) + MethodItem((sig, &self.generics, body).clean(cx)) } hir::TraitItemKind::Method(ref sig, hir::TraitMethod::Required(ref names)) => { TyMethodItem(TyMethod { unsafety: sig.unsafety.clone(), decl: (&*sig.decl, &names[..]).clean(cx), - generics: sig.generics.clean(cx), + generics: self.generics.clean(cx), abi: sig.abi }) } @@ -1412,7 +1566,7 @@ impl Clean<Item> for hir::ImplItem { Some(print_const_expr(cx, expr))) } hir::ImplItemKind::Method(ref sig, body) => { - MethodItem((sig, body).clean(cx)) + MethodItem((sig, &self.generics, body).clean(cx)) } hir::ImplItemKind::Type(ref ty) => TypedefItem(Typedef { type_: ty.clean(cx), @@ -1441,7 +1595,12 @@ impl<'tcx> Clean<Item> for ty::AssociatedItem { let inner = match self.kind { ty::AssociatedKind::Const => { let ty = cx.tcx.type_of(self.def_id); - AssociatedConstItem(ty.clean(cx), None) + let default = if self.defaultness.has_value() { + Some(inline::print_inlined_const(cx, self.def_id)) + } else { + None + }; + AssociatedConstItem(ty.clean(cx), default) } ty::AssociatedKind::Method => { let generics = (cx.tcx.generics_of(self.def_id), @@ -1472,18 +1631,21 @@ impl<'tcx> Clean<Item> for ty::AssociatedItem { } let provided = match self.container { - ty::ImplContainer(_) => false, + ty::ImplContainer(_) => true, ty::TraitContainer(_) => self.defaultness.has_value() }; if provided { + let constness = if cx.tcx.is_const_fn(self.def_id) { + hir::Constness::Const + } else { + hir::Constness::NotConst + }; MethodItem(Method { unsafety: sig.unsafety(), generics, decl, abi: sig.abi(), - - // trait methods cannot (currently, at least) be const - constness: hir::Constness::NotConst, + constness, }) } else { TyMethodItem(TyMethod { @@ -1497,14 +1659,14 @@ impl<'tcx> Clean<Item> for ty::AssociatedItem { ty::AssociatedKind::Type => { let my_name = self.name.clean(cx); - let mut bounds = if let ty::TraitContainer(did) = self.container { + if let ty::TraitContainer(did) = self.container { // When loading a cross-crate associated type, the bounds for this type // are actually located on the trait/impl itself, so we need to load // all of the generics from there and then look for bounds that are // applied to this associated type in question. let predicates = cx.tcx.predicates_of(did); let generics = (cx.tcx.generics_of(did), &predicates).clean(cx); - generics.where_predicates.iter().filter_map(|pred| { + let mut bounds = generics.where_predicates.iter().filter_map(|pred| { let (name, self_type, trait_, bounds) = match *pred { WherePredicate::BoundPredicate { ty: QPath { ref name, ref self_type, ref trait_ }, @@ -1522,34 +1684,45 @@ impl<'tcx> Clean<Item> for ty::AssociatedItem { _ => return None, } Some(bounds) - }).flat_map(|i| i.iter().cloned()).collect::<Vec<_>>() - } else { - vec![] - }; + }).flat_map(|i| i.iter().cloned()).collect::<Vec<_>>(); + // Our Sized/?Sized bound didn't get handled when creating the generics + // because we didn't actually get our whole set of bounds until just now + // (some of them may have come from the trait). If we do have a sized + // bound, we remove it, and if we don't then we add the `?Sized` bound + // at the end. + match bounds.iter().position(|b| b.is_sized_bound(cx)) { + Some(i) => { bounds.remove(i); } + None => bounds.push(TyParamBound::maybe_sized(cx)), + } - // Our Sized/?Sized bound didn't get handled when creating the generics - // because we didn't actually get our whole set of bounds until just now - // (some of them may have come from the trait). If we do have a sized - // bound, we remove it, and if we don't then we add the `?Sized` bound - // at the end. - match bounds.iter().position(|b| b.is_sized_bound(cx)) { - Some(i) => { bounds.remove(i); } - None => bounds.push(TyParamBound::maybe_sized(cx)), - } + let ty = if self.defaultness.has_value() { + Some(cx.tcx.type_of(self.def_id)) + } else { + None + }; - let ty = if self.defaultness.has_value() { - Some(cx.tcx.type_of(self.def_id)) + AssociatedTypeItem(bounds, ty.clean(cx)) } else { - None - }; - - AssociatedTypeItem(bounds, ty.clean(cx)) + TypedefItem(Typedef { + type_: cx.tcx.type_of(self.def_id).clean(cx), + generics: Generics { + lifetimes: Vec::new(), + type_params: Vec::new(), + where_predicates: Vec::new(), + }, + }, true) + } } }; + let visibility = match self.container { + ty::ImplContainer(_) => self.vis.clean(cx), + ty::TraitContainer(_) => None, + }; + Item { name: Some(self.name.clean(cx)), - visibility: Some(Inherited), + visibility, stability: get_stability(cx, self.def_id), deprecation: get_deprecation(cx, self.def_id), def_id: self.def_id, @@ -1625,6 +1798,7 @@ pub enum PrimitiveType { Slice, Array, Tuple, + Unit, RawPointer, Reference, Fn, @@ -1642,6 +1816,7 @@ pub enum TypeKind { Trait, Variant, Typedef, + Foreign, } pub trait GetDefId { @@ -1660,7 +1835,11 @@ impl Type { Primitive(p) | BorrowedRef { type_: box Primitive(p), ..} => Some(p), Slice(..) | BorrowedRef { type_: box Slice(..), .. } => Some(PrimitiveType::Slice), Array(..) | BorrowedRef { type_: box Array(..), .. } => Some(PrimitiveType::Array), - Tuple(..) => Some(PrimitiveType::Tuple), + Tuple(ref tys) => if tys.is_empty() { + Some(PrimitiveType::Unit) + } else { + Some(PrimitiveType::Tuple) + }, RawPointer(..) => Some(PrimitiveType::RawPointer), BorrowedRef { type_: box Generic(..), .. } => Some(PrimitiveType::Reference), BareFunction(..) => Some(PrimitiveType::Fn), @@ -1681,6 +1860,21 @@ impl Type { _ => false } } + + pub fn generics(&self) -> Option<&[Type]> { + match *self { + ResolvedPath { ref path, .. } => { + path.segments.last().and_then(|seg| { + if let PathParameters::AngleBracketed { ref types, .. } = seg.params { + Some(&**types) + } else { + None + } + }) + } + _ => None, + } + } } impl GetDefId for Type { @@ -1691,7 +1885,11 @@ impl GetDefId for Type { BorrowedRef { type_: box Generic(..), .. } => Primitive(PrimitiveType::Reference).def_id(), BorrowedRef { ref type_, .. } => type_.def_id(), - Tuple(..) => Primitive(PrimitiveType::Tuple).def_id(), + Tuple(ref tys) => if tys.is_empty() { + Primitive(PrimitiveType::Unit).def_id() + } else { + Primitive(PrimitiveType::Tuple).def_id() + }, BareFunction(..) => Primitive(PrimitiveType::Fn).def_id(), Slice(..) => Primitive(PrimitiveType::Slice).def_id(), Array(..) => Primitive(PrimitiveType::Array).def_id(), @@ -1725,6 +1923,7 @@ impl PrimitiveType { "array" => Some(PrimitiveType::Array), "slice" => Some(PrimitiveType::Slice), "tuple" => Some(PrimitiveType::Tuple), + "unit" => Some(PrimitiveType::Unit), "pointer" => Some(PrimitiveType::RawPointer), "reference" => Some(PrimitiveType::Reference), "fn" => Some(PrimitiveType::Fn), @@ -1755,6 +1954,7 @@ impl PrimitiveType { Array => "array", Slice => "slice", Tuple => "tuple", + Unit => "unit", RawPointer => "pointer", Reference => "reference", Fn => "fn", @@ -1928,7 +2128,8 @@ impl Clean<Type> for hir::Ty { } } TyBareFn(ref barefn) => BareFunction(box barefn.clean(cx)), - TyImplTrait(ref bounds) => ImplTrait(bounds.clean(cx)), + TyImplTraitExistential(ref exist_ty, ref _lts) => ImplTrait(exist_ty.bounds.clean(cx)), + TyImplTraitUniversal(_, ref bounds) => ImplTrait(bounds.clean(cx)), TyInfer | TyErr => Infer, TyTypeof(..) => panic!("Unimplemented type {:?}", self.node), } @@ -1998,6 +2199,17 @@ impl<'tcx> Clean<Type> for Ty<'tcx> { is_generic: false, } } + ty::TyForeign(did) => { + inline::record_extern_fqn(cx, did, TypeKind::Foreign); + let path = external_path(cx, &cx.tcx.item_name(did), + None, false, vec![], Substs::empty()); + ResolvedPath { + path: path, + typarams: None, + did: did, + is_generic: false, + } + } ty::TyDynamic(ref obj, ref reg) => { if let Some(principal) = obj.principal() { let did = principal.def_id(); @@ -2491,7 +2703,7 @@ impl Clean<BareFunctionDecl> for hir::BareFnTy { type_params: Vec::new(), where_predicates: Vec::new() }, - decl: (&*self.decl, &[][..]).clean(cx), + decl: (&*self.decl, &self.arg_names[..]).clean(cx), abi: self.abi, } } @@ -2676,6 +2888,7 @@ fn build_deref_target_impls(cx: &DocContext, Slice => tcx.lang_items().slice_impl(), Array => tcx.lang_items().slice_impl(), Tuple => None, + Unit => None, RawPointer => tcx.lang_items().const_ptr_impl(), Reference => None, Fn => None, @@ -2689,12 +2902,12 @@ fn build_deref_target_impls(cx: &DocContext, } #[derive(Clone, RustcEncodable, RustcDecodable, Debug)] -pub struct DefaultImpl { +pub struct AutoImpl { pub unsafety: hir::Unsafety, pub trait_: Type, } -impl Clean<Item> for doctree::DefaultImpl { +impl Clean<Item> for doctree::AutoImpl { fn clean(&self, cx: &DocContext) -> Item { Item { name: None, @@ -2704,7 +2917,7 @@ impl Clean<Item> for doctree::DefaultImpl { visibility: Some(Public), stability: None, deprecation: None, - inner: DefaultImplItem(DefaultImpl { + inner: AutoImplItem(AutoImpl { unsafety: self.unsafety, trait_: self.trait_.clean(cx), }), @@ -2810,6 +3023,9 @@ impl Clean<Item> for hir::ForeignItem { expr: "".to_string(), }) } + hir::ForeignItemType => { + ForeignTypeItem + } }; Item { name: Some(self.name.clean(cx)), @@ -2921,6 +3137,7 @@ fn register_def(cx: &DocContext, def: Def) -> DefId { Def::Struct(i) => (i, TypeKind::Struct), Def::Union(i) => (i, TypeKind::Union), Def::Mod(i) => (i, TypeKind::Module), + Def::TyForeign(i) => (i, TypeKind::Foreign), Def::Static(i, _) => (i, TypeKind::Static), Def::Variant(i) => (cx.tcx.parent_def_id(i).unwrap(), TypeKind::Enum), Def::SelfTy(Some(def_id), _) => (def_id, TypeKind::Trait), |