OpenE2K/rust
2
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

Auto merge of #41084 - QuietMisdreavus:rustdoc-format-redux, r=frewsxcxv,GuillaumeGomez

Browse Source 
rustdoc: update formatting of fn signatures and where clauses to match style rfcs

Recent updates to style RFCs ([where clauses](https://github.com/rust-lang-nursery/fmt-rfcs/issues/38), [function definitions](https://github.com/rust-lang-nursery/fmt-rfcs/issues/39)) changed the "canonical" style for these items, so this is a rustdoc update to make it emit that style where necessary. This is mainly a conversion from visual indent to block indent, which helps out in situations where there was excessive indent causing lines to wrap regardless.

Samples:

![std::iter::IntoIterator](https://cloud.githubusercontent.com/assets/5217170/24712947/e586604c-19e9-11e7-87ae-4fe64d689dc3.png)

![excerpt from std::iter::Iterator](https://cloud.githubusercontent.com/assets/5217170/24713209/91e65112-19ea-11e7-9ff8-d4cf6b31aae1.png)

![std::iter::FromIterator](https://cloud.githubusercontent.com/assets/5217170/24713138/59f36114-19ea-11e7-9dbb-5f5ba7126e2e.png)

![std::cmp::min](https://cloud.githubusercontent.com/assets/5217170/24713038/1bab88b4-19ea-11e7-935d-defed5648de4.png)

![some trait impls on std::collections::HashMap](https://cloud.githubusercontent.com/assets/5217170/24713251/b7ef69e8-19ea-11e7-94a7-e01fbf89fa31.png)

![`fn extract_code_blocks`, an example given in #40687](https://cloud.githubusercontent.com/assets/5217170/24713159/672717cc-19ea-11e7-9acb-6ac278b90339.png)

![excerpt from itertools::Itertools](https://cloud.githubusercontent.com/assets/5217170/24713323/f06716ea-19ea-11e7-94cc-6ef68d9980ec.png)

fixes #41025 and #40687

r? @rust-lang/docs
This commit is contained in:
bors 2017-04-09 17:51:32 +00:00
commit d616f47cd0
6 changed files with 137 additions and 133 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

134
src/librustdoc/html/format.rs
View File

@ -41,22 +41,38 @@ pub struct UnsafetySpace(pub hir::Unsafety);
/// with a space after it.
#[derive(Copy, Clone)]
pub struct ConstnessSpace(pub hir::Constness);
/// Wrapper struct for properly emitting a method declaration.
pub struct Method<'a>(pub &'a clean::FnDecl, pub usize);
/// Similar to VisSpace, but used for mutability
#[derive(Copy, Clone)]
pub struct MutableSpace(pub clean::Mutability);
/// Similar to VisSpace, but used for mutability
#[derive(Copy, Clone)]
pub struct RawMutableSpace(pub clean::Mutability);
/// Wrapper struct for emitting a where clause from Generics.
pub struct WhereClause<'a>(pub &'a clean::Generics, pub usize);
/// Wrapper struct for emitting type parameter bounds.
pub struct TyParamBounds<'a>(pub &'a [clean::TyParamBound]);
/// Wrapper struct for emitting a comma-separated list of items
pub struct CommaSep<'a, T: 'a>(pub &'a [T]);
pub struct AbiSpace(pub Abi);
/// Wrapper struct for properly emitting a method declaration.
pub struct Method<'a> {
/// The declaration to emit.
pub decl: &'a clean::FnDecl,
/// The length of the function's "name", used to determine line-wrapping.
pub name_len: usize,
/// The number of spaces to indent each successive line with, if line-wrapping is necessary.
pub indent: usize,
}
/// Wrapper struct for emitting a where clause from Generics.
pub struct WhereClause<'a>{
/// The Generics from which to emit a where clause.
pub gens: &'a clean::Generics,
/// The number of spaces to indent each line with.
pub indent: usize,
/// Whether the where clause needs to add a comma and newline after the last bound.
pub end_newline: bool,
}
pub struct HRef<'a> {
pub did: DefId,
pub text: &'a str,
@ -167,24 +183,27 @@ impl fmt::Display for clean::Generics {
impl<'a> fmt::Display for WhereClause<'a> {
fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
let &WhereClause(gens, pad) = self;
let &WhereClause { gens, indent, end_newline } = self;
if gens.where_predicates.is_empty() {
return Ok(());
}
let mut clause = String::new();
if f.alternate() {
clause.push_str(" where ");
clause.push_str(" where");
} else {
clause.push_str(" <span class=\"where fmt-newline\">where ");
if end_newline {
clause.push_str(" <span class=\"where fmt-newline\">where");
} else {
clause.push_str(" <span class=\"where\">where");
}
}
for (i, pred) in gens.where_predicates.iter().enumerate() {
if i > 0 {
if f.alternate() {
clause.push_str(", ");
} else {
clause.push_str(",<br>");
}
if f.alternate() {
clause.push(' ');
} else {
clause.push_str("<br>");
}
match pred {
&clean::WherePredicate::BoundPredicate { ref ty, ref bounds } => {
let bounds = bounds;
@ -213,21 +232,29 @@ impl<'a> fmt::Display for WhereClause<'a> {
}
}
}
if i < gens.where_predicates.len() - 1 || end_newline {
clause.push(',');
}
}
if end_newline {
//add a space so stripping <br> tags and breaking spaces still renders properly
if f.alternate() {
clause.push(' ');
} else {
clause.push_str("&nbsp;");
}
}
if !f.alternate() {
clause.push_str("</span>");
let plain = format!("{:#}", self);
if plain.len() + pad > 80 {
// break it onto its own line regardless, but make sure method impls and trait
// blocks keep their fixed padding (2 and 9, respectively)
let padding = if pad > 10 {
repeat("&nbsp;").take(8).collect::<String>()
} else {
repeat("&nbsp;").take(pad + 6).collect::<String>()
};
clause = clause.replace("<br>", &format!("<br>{}", padding));
} else {
clause = clause.replace("<br>", " ");
let padding = repeat("&nbsp;").take(indent + 4).collect::<String>();
clause = clause.replace("<br>", &format!("<br>{}", padding));
clause.insert_str(0, &repeat("&nbsp;").take(indent.saturating_sub(1))
.collect::<String>());
if !end_newline {
clause.insert_str(0, "<br>");
}
}
write!(f, "{}", clause)
@ -838,43 +865,35 @@ fn fmt_impl(i: &clean::Impl,
f: &mut fmt::Formatter,
link_trait: bool,
use_absolute: bool) -> fmt::Result {
let mut plain = String::new();
if f.alternate() {
write!(f, "impl{:#} ", i.generics)?;
} else {
write!(f, "impl{} ", i.generics)?;
}
plain.push_str(&format!("impl{:#} ", i.generics));
if let Some(ref ty) = i.trait_ {
if i.polarity == Some(clean::ImplPolarity::Negative) {
write!(f, "!")?;
plain.push_str("!");
}
if link_trait {
fmt::Display::fmt(ty, f)?;
plain.push_str(&format!("{:#}", ty));
} else {
match *ty {
clean::ResolvedPath { typarams: None, ref path, is_generic: false, .. } => {
let last = path.segments.last().unwrap();
fmt::Display::fmt(&last.name, f)?;
fmt::Display::fmt(&last.params, f)?;
plain.push_str(&format!("{:#}{:#}", last.name, last.params));
}
_ => unreachable!(),
}
}
write!(f, " for ")?;
plain.push_str(" for ");
}
fmt_type(&i.for_, f, use_absolute, true)?;
plain.push_str(&format!("{:#}", i.for_));
fmt::Display::fmt(&WhereClause(&i.generics, plain.len() + 1), f)?;
fmt::Display::fmt(&WhereClause { gens: &i.generics, indent: 0, end_newline: true }, f)?;
Ok(())
}
@ -939,12 +958,15 @@ impl fmt::Display for clean::FnDecl {
impl<'a> fmt::Display for Method<'a> {
fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
let decl = self.0;
let indent = self.1;
let &Method { decl, name_len, indent } = self;
let amp = if f.alternate() { "&" } else { "&amp;" };
let mut args = String::new();
let mut args_plain = String::new();
for (i, input) in decl.inputs.values.iter().enumerate() {
if i == 0 {
args.push_str("<br>");
}
if let Some(selfty) = input.to_self() {
match selfty {
clean::SelfValue => {
@ -970,7 +992,7 @@ impl<'a> fmt::Display for Method<'a> {
}
} else {
if i > 0 {
args.push_str("<br> ");
args.push_str(" <br>");
args_plain.push_str(" ");
}
if !input.name.is_empty() {
@ -986,8 +1008,8 @@ impl<'a> fmt::Display for Method<'a> {
args_plain.push_str(&format!("{:#}", input.type_));
}
if i + 1 < decl.inputs.values.len() {
args.push_str(",");
args_plain.push_str(",");
args.push(',');
args_plain.push(',');
}
}
@ -1003,27 +1025,23 @@ impl<'a> fmt::Display for Method<'a> {
format!("{}", decl.output)
};
let mut output: String;
let plain: String;
let pad = repeat(" ").take(indent).collect::<String>();
if arrow.is_empty() {
output = format!("({})", args);
plain = format!("{}({})", pad, args_plain);
} else {
output = format!("({args})<br>{arrow}", args = args, arrow = arrow);
plain = format!("{pad}({args}){arrow}",
pad = pad,
args = args_plain,
arrow = arrow_plain);
}
let pad = repeat(" ").take(name_len).collect::<String>();
let plain = format!("{pad}({args}){arrow}",
pad = pad,
args = args_plain,
arrow = arrow_plain);
if plain.len() > 80 {
let pad = repeat("&nbsp;").take(indent).collect::<String>();
let pad = format!("<br>{}", pad);
output = output.replace("<br>", &pad);
let output = if plain.len() > 80 {
let full_pad = format!("<br>{}", repeat("&nbsp;").take(indent + 4).collect::<String>());
let close_pad = format!("<br>{}", repeat("&nbsp;").take(indent).collect::<String>());
format!("({args}{close}){arrow}",
args = args.replace("<br>", &full_pad),
close = close_pad,
arrow = arrow)
} else {
output = output.replace("<br>", "");
}
format!("({args}){arrow}", args = args.replace("<br>", ""), arrow = arrow)
};
if f.alternate() {
write!(f, "{}", output.replace("<br>", "\n"))
} else {

113
src/librustdoc/html/render.rs
View File

@ -2016,13 +2016,13 @@ fn item_function(w: &mut fmt::Formatter, cx: &Context, it: &clean::Item,
UnstableFeatures::Allow => f.constness,
_ => hir::Constness::NotConst
};
let indent = format!("{}{}{}{:#}fn {}{:#}",
VisSpace(&it.visibility),
ConstnessSpace(vis_constness),
UnsafetySpace(f.unsafety),
AbiSpace(f.abi),
it.name.as_ref().unwrap(),
f.generics).len();
let name_len = format!("{}{}{}{:#}fn {}{:#}",
VisSpace(&it.visibility),
ConstnessSpace(vis_constness),
UnsafetySpace(f.unsafety),
AbiSpace(f.abi),
it.name.as_ref().unwrap(),
f.generics).len();
write!(w, "<pre class='rust fn'>")?;
render_attributes(w, it)?;
write!(w, "{vis}{constness}{unsafety}{abi}fn \
@ -2033,8 +2033,12 @@ fn item_function(w: &mut fmt::Formatter, cx: &Context, it: &clean::Item,
abi = AbiSpace(f.abi),
name = it.name.as_ref().unwrap(),
generics = f.generics,
where_clause = WhereClause(&f.generics, 2),
decl = Method(&f.decl, indent))?;
where_clause = WhereClause { gens: &f.generics, indent: 0, end_newline: true },
decl = Method {
decl: &f.decl,
name_len: name_len,
indent: 0,
})?;
document(w, cx, it)
}
@ -2062,14 +2066,18 @@ fn item_trait(w: &mut fmt::Formatter, cx: &Context, it: &clean::Item,
// Output the trait definition
write!(w, "<pre class='rust trait'>")?;
render_attributes(w, it)?;
write!(w, "{}{}trait {}{}{}{} ",
write!(w, "{}{}trait {}{}{}",
VisSpace(&it.visibility),
UnsafetySpace(t.unsafety),
it.name.as_ref().unwrap(),
t.generics,
bounds,
// Where clauses in traits are indented nine spaces, per rustdoc.css
WhereClause(&t.generics, 9))?;
bounds)?;
if !t.generics.where_predicates.is_empty() {
write!(w, "{}", WhereClause { gens: &t.generics, indent: 0, end_newline: true })?;
} else {
write!(w, " ")?;
}
let types = t.items.iter().filter(|m| m.is_associated_type()).collect::<Vec<_>>();
let consts = t.items.iter().filter(|m| m.is_associated_const()).collect::<Vec<_>>();
@ -2108,7 +2116,14 @@ fn item_trait(w: &mut fmt::Formatter, cx: &Context, it: &clean::Item,
for m in &provided {
write!(w, " ")?;
render_assoc_item(w, m, AssocItemLink::Anchor(None), ItemType::Trait)?;
write!(w, " {{ ... }}\n")?;
match m.inner {
clean::MethodItem(ref inner) if !inner.generics.where_predicates.is_empty() => {
write!(w, ",\n {{ ... }}\n")?;
},
_ => {
write!(w, " {{ ... }}\n")?;
},
}
}
write!(w, "}}")?;
}
@ -2342,21 +2357,17 @@ fn render_assoc_item(w: &mut fmt::Formatter,
} else {
hir::Constness::NotConst
};
let prefix = format!("{}{}{:#}fn {}{:#}",
ConstnessSpace(vis_constness),
UnsafetySpace(unsafety),
AbiSpace(abi),
name,
*g);
let mut indent = prefix.len();
let where_indent = if parent == ItemType::Trait {
indent += 4;
8
} else if parent == ItemType::Impl {
2
let mut head_len = format!("{}{}{:#}fn {}{:#}",
ConstnessSpace(vis_constness),
UnsafetySpace(unsafety),
AbiSpace(abi),
name,
*g).len();
let (indent, end_newline) = if parent == ItemType::Trait {
head_len += 4;
(4, false)
} else {
let prefix = prefix + &format!("{:#}", Method(d, indent));
prefix.lines().last().unwrap().len() + 1
(0, true)
};
write!(w, "{}{}{}fn <a href='{href}' class='fnname'>{name}</a>\
{generics}{decl}{where_clause}",
@ -2366,8 +2377,16 @@ fn render_assoc_item(w: &mut fmt::Formatter,
href = href,
name = name,
generics = *g,
decl = Method(d, indent),
where_clause = WhereClause(g, where_indent))
decl = Method {
decl: d,
name_len: head_len,
indent: indent,
},
where_clause = WhereClause {
gens: g,
indent: indent,
end_newline: end_newline,
})
}
match item.inner {
clean::StrippedItem(..) => Ok(()),
@ -2480,15 +2499,11 @@ fn item_enum(w: &mut fmt::Formatter, cx: &Context, it: &clean::Item,
e: &clean::Enum) -> fmt::Result {
write!(w, "<pre class='rust enum'>")?;
render_attributes(w, it)?;
let padding = format!("{}enum {}{:#} ",
VisSpace(&it.visibility),
it.name.as_ref().unwrap(),
e.generics).len();
write!(w, "{}enum {}{}{}",
VisSpace(&it.visibility),
it.name.as_ref().unwrap(),
e.generics,
WhereClause(&e.generics, padding))?;
WhereClause { gens: &e.generics, indent: 0, end_newline: true })?;
if e.variants.is_empty() && !e.variants_stripped {
write!(w, " {{}}")?;
} else {
@ -2662,23 +2677,17 @@ fn render_struct(w: &mut fmt::Formatter, it: &clean::Item,
fields: &[clean::Item],
tab: &str,
structhead: bool) -> fmt::Result {
let mut plain = String::new();
write!(w, "{}{}{}",
VisSpace(&it.visibility),
if structhead {"struct "} else {""},
it.name.as_ref().unwrap())?;
plain.push_str(&format!("{}{}{}",
VisSpace(&it.visibility),
if structhead {"struct "} else {""},
it.name.as_ref().unwrap()));
if let Some(g) = g {
plain.push_str(&format!("{:#}", g));
write!(w, "{}", g)?
}
match ty {
doctree::Plain => {
if let Some(g) = g {
write!(w, "{}", WhereClause(g, plain.len() + 1))?
write!(w, "{}", WhereClause { gens: g, indent: 0, end_newline: true })?
}
let mut has_visible_fields = false;
write!(w, " {{")?;
@ -2707,35 +2716,30 @@ fn render_struct(w: &mut fmt::Formatter, it: &clean::Item,
}
doctree::Tuple => {
write!(w, "(")?;
plain.push_str("(");
for (i, field) in fields.iter().enumerate() {
if i > 0 {
write!(w, ", ")?;
plain.push_str(", ");
}
match field.inner {
clean::StrippedItem(box clean::StructFieldItem(..)) => {
plain.push_str("_");
write!(w, "_")?
}
clean::StructFieldItem(ref ty) => {
plain.push_str(&format!("{}{:#}", VisSpace(&field.visibility), *ty));
write!(w, "{}{}", VisSpace(&field.visibility), *ty)?
}
_ => unreachable!()
}
}
write!(w, ")")?;
plain.push_str(")");
if let Some(g) = g {
write!(w, "{}", WhereClause(g, plain.len() + 1))?
write!(w, "{}", WhereClause { gens: g, indent: 0, end_newline: false })?
}
write!(w, ";")?;
}
doctree::Unit => {
// Needed for PhantomData.
if let Some(g) = g {
write!(w, "{}", WhereClause(g, plain.len() + 1))?
write!(w, "{}", WhereClause { gens: g, indent: 0, end_newline: false })?
}
write!(w, ";")?;
}
@ -2748,19 +2752,13 @@ fn render_union(w: &mut fmt::Formatter, it: &clean::Item,
fields: &[clean::Item],
tab: &str,
structhead: bool) -> fmt::Result {
let mut plain = String::new();
write!(w, "{}{}{}",
VisSpace(&it.visibility),
if structhead {"union "} else {""},
it.name.as_ref().unwrap())?;
plain.push_str(&format!("{}{}{}",
VisSpace(&it.visibility),
if structhead {"union "} else {""},
it.name.as_ref().unwrap()));
if let Some(g) = g {
write!(w, "{}", g)?;
plain.push_str(&format!("{:#}", g));
write!(w, "{}", WhereClause(g, plain.len() + 1))?;
write!(w, "{}", WhereClause { gens: g, indent: 0, end_newline: true })?;
}
write!(w, " {{\n{}", tab)?;
@ -3059,13 +3057,12 @@ fn render_impl(w: &mut fmt::Formatter, cx: &Context, i: &Impl, link: AssocItemLi
fn item_typedef(w: &mut fmt::Formatter, cx: &Context, it: &clean::Item,
t: &clean::Typedef) -> fmt::Result {
let indent = format!("type {}{:#} ", it.name.as_ref().unwrap(), t.generics).len();
write!(w, "<pre class='rust typedef'>")?;
render_attributes(w, it)?;
write!(w, "type {}{}{where_clause} = {type_};</pre>",
it.name.as_ref().unwrap(),
t.generics,
where_clause = WhereClause(&t.generics, indent),
where_clause = WhereClause { gens: &t.generics, indent: 0, end_newline: true },
type_ = t.type_)?;
document(w, cx, it)

13
src/librustdoc/html/static/rustdoc.css
View File

@ -379,12 +379,6 @@ h4 > code, h3 > code, .invisible > code {
.content .where.fmt-newline {
display: block;
}
/* Bit of whitespace to indent it */
.content .method .where::before,
.content .fn .where::before,
.content .where.fmt-newline::before {
content: ' ';
}
.content .methods > div { margin-left: 40px; }
@ -399,11 +393,6 @@ h4 > code, h3 > code, .invisible > code {
font-size: 90%;
}
/* Shift where in trait listing down a line */
pre.trait .where::before {
content: '\a ';
}
nav {
border-bottom: 1px solid;
padding-bottom: 10px;
@ -772,4 +761,4 @@ span.since {
nav.sub, .content .out-of-band, .collapse-toggle {
display: none;
}
}
}

4
src/test/rustdoc/impl-parts.rs
View File

@ -17,7 +17,7 @@ impl AnOibit for .. {}
pub struct Foo<T> { field: T }
// @has impl_parts/struct.Foo.html '//*[@class="impl"]//code' \
// "impl<T: Clone> !AnOibit for Foo<T> where T: Sync"
// "impl<T: Clone> !AnOibit for Foo<T> where T: Sync,"
// @has impl_parts/trait.AnOibit.html '//*[@class="item-list"]//code' \
// "impl<T: Clone> !AnOibit for Foo<T> where T: Sync"
// "impl<T: Clone> !AnOibit for Foo<T> where T: Sync,"
impl<T: Clone> !AnOibit for Foo<T> where T: Sync {}

4
src/test/rustdoc/issue-20727-4.rs
View File

@ -35,7 +35,7 @@ pub trait IndexMut<Idx: ?Sized>: Index<Idx> {
pub mod reexport {
// @has issue_20727_4/reexport/trait.Index.html
// @has - '//*[@class="rust trait"]' 'trait Index<Idx> where Idx: ?Sized {'
// @has - '//*[@class="rust trait"]' 'trait Index<Idx> where Idx: ?Sized, {'
// @has - '//*[@class="rust trait"]' 'type Output: ?Sized'
// @has - '//*[@class="rust trait"]' \
// 'fn index(&self, index: Idx) -> &Self::Output'
@ -43,7 +43,7 @@ pub mod reexport {
// @has issue_20727_4/reexport/trait.IndexMut.html
// @has - '//*[@class="rust trait"]' \
// 'trait IndexMut<Idx>: Index<Idx> where Idx: ?Sized {'
// 'trait IndexMut<Idx>: Index<Idx> where Idx: ?Sized, {'
// @has - '//*[@class="rust trait"]' \
// 'fn index_mut(&mut self, index: Idx) -> &mut Self::Output;'
pub use issue_20727::IndexMut;

2
src/test/rustdoc/where.rs
View File

@ -44,5 +44,5 @@ pub enum Foxtrot<F> { Foxtrot1(F) }
impl<F> MyTrait for Foxtrot<F> where F: MyTrait {}
// @has foo/type.Golf.html '//pre[@class="rust typedef"]' \
// "type Golf<T> where T: Clone = (T, T)"
// "type Golf<T> where T: Clone, = (T, T)"
pub type Golf<T> where T: Clone = (T, T);