user0/rust
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Auto merge of #43560 - QuietMisdreavus:ref-docs, r=steveklabnik

Browse source 
add docs for references as a primitive

Just like #43529 did for function pointers, here is a new primitive page for references.

This PR will pull in impls on references if it's a reference to a generic type parameter. Initially i was only able to pull in impls that were re-exported from another crate; crate-local impls got a different representation in the AST, and i had to change how types were resolved when cleaning it. (This is the change at the bottom of `librustdoc/clean/mod.rs`, in `resolve_type`.) I'm unsure the full ramifications of the change, but from what it looks like, it shouldn't impact anything major. Likewise, references to generic type parameters also get the `&'a [mut]` linked to the new page.

cc @rust-lang/docs: Is this sufficient information? The listing of trait impls kinda feels redundant (especially if we can get the automated impl listing sorted again), but i still think it's useful to point out that you can use these in a generic context.

Fixes #15654
This commit is contained in:
bors 2017-08-01 08:23:41 +00:00
commit 0bf018c588
3 changed files with 142 additions and 19 deletions
Download patch file Download diff file Expand all files Collapse all files

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

@ -1547,6 +1547,7 @@ pub enum PrimitiveType {
Array,
Tuple,
RawPointer,
Reference,
}
#[derive(Clone, RustcEncodable, RustcDecodable, Copy, Debug)]
@ -1581,6 +1582,7 @@ impl Type {
Array(..) | BorrowedRef { type_: box Array(..), .. } => Some(PrimitiveType::Array),
Tuple(..) => Some(PrimitiveType::Tuple),
RawPointer(..) => Some(PrimitiveType::RawPointer),
BorrowedRef { type_: box Generic(..), .. } => Some(PrimitiveType::Reference),
_ => None,
}
}
@ -1633,6 +1635,7 @@ impl PrimitiveType {
"slice" => Some(PrimitiveType::Slice),
"tuple" => Some(PrimitiveType::Tuple),
"pointer" => Some(PrimitiveType::RawPointer),
"reference" => Some(PrimitiveType::Reference),
_ => None,
}
}
@ -1661,6 +1664,7 @@ impl PrimitiveType {
Slice => "slice",
Tuple => "tuple",
RawPointer => "pointer",
Reference => "reference",
}
}
@ -2556,6 +2560,7 @@ fn build_deref_target_impls(cx: &DocContext,
Array => tcx.lang_items.slice_impl(),
Tuple => None,
RawPointer => tcx.lang_items.const_ptr_impl(),
Reference => None,
};
if let Some(did) = did {
if !did.is_local() {
@ -2777,6 +2782,9 @@ fn resolve_type(cx: &DocContext,
Def::SelfTy(..) if path.segments.len() == 1 => {
return Generic(keywords::SelfType.name().to_string());
}
Def::TyParam(..) if path.segments.len() == 1 => {
return Generic(format!("{:#}", path));
}
Def::SelfTy(..) | Def::TyParam(..) | Def::AssociatedTy(..) => true,
_ => false,
};

36
src/librustdoc/html/format.rs
View file

@ -665,26 +665,29 @@ fn fmt_type(t: &clean::Type, f: &mut fmt::Formatter, use_absolute: bool) -> fmt:
_ => "".to_string(),
};
let m = MutableSpace(mutability);
let amp = if f.alternate() {
"&".to_string()
} else {
"&".to_string()
};
match **ty {
clean::Slice(ref bt) => { // BorrowedRef{ ... Slice(T) } is &[T]
match **bt {
clean::Generic(_) => {
if f.alternate() {
primitive_link(f, PrimitiveType::Slice,
&format!("&{}{}[{:#}]", lt, m, **bt))
&format!("{}{}{}[{:#}]", amp, lt, m, **bt))
} else {
primitive_link(f, PrimitiveType::Slice,
&format!("&{}{}[{}]", lt, m, **bt))
&format!("{}{}{}[{}]", amp, lt, m, **bt))
}
}
_ => {
primitive_link(f, PrimitiveType::Slice,
&format!("{}{}{}[", amp, lt, m))?;
if f.alternate() {
primitive_link(f, PrimitiveType::Slice,
&format!("&{}{}[", lt, m))?;
write!(f, "{:#}", **bt)?;
} else {
primitive_link(f, PrimitiveType::Slice,
&format!("&{}{}[", lt, m))?;
write!(f, "{}", **bt)?;
}
primitive_link(f, PrimitiveType::Slice, "]")
@ -692,23 +695,18 @@ fn fmt_type(t: &clean::Type, f: &mut fmt::Formatter, use_absolute: bool) -> fmt:
}
}
clean::ResolvedPath { typarams: Some(ref v), .. } if !v.is_empty() => {
if f.alternate() {
write!(f, "&{}{}", lt, m)?;
} else {
write!(f, "&{}{}", lt, m)?;
}
write!(f, "(")?;
write!(f, "{}{}{}(", amp, lt, m)?;
fmt_type(&ty, f, use_absolute)?;
write!(f, ")")
}
clean::Generic(..) => {
primitive_link(f, PrimitiveType::Reference,
&format!("{}{}{}", amp, lt, m))?;
fmt_type(&ty, f, use_absolute)
}
_ => {
if f.alternate() {
write!(f, "&{}{}", lt, m)?;
fmt_type(&ty, f, use_absolute)
} else {
write!(f, "&{}{}", lt, m)?;
fmt_type(&ty, f, use_absolute)
}
write!(f, "{}{}{}", amp, lt, m)?;
fmt_type(&ty, f, use_absolute)
}
}
}