1
Fork 0

Rollup merge of #36679 - QuietMisdreavus:rustdoc-line-breaks, r=steveklabnik

rustdoc: print non-self arguments of bare functions and struct methods on their own line

This change alters the formatting rustdoc uses when it creates function and struct method documentation. For bare functions, each argument is printed on its own line. For struct methods, non-self arguments are printed on their own line. In both cases, no line breaks are introduced if there are no arguments, and for struct methods, no line breaks are introduced if there is only a single self argument. This should aid readability of long function signatures and allow for greater comprehension of these functions.

I've run rustdoc with these changes on my crate egg-mode and its set of dependencies and put the result [on my server](https://shiva.icesoldier.me/doc-custom/egg_mode/). Of note, here are a few shortcut links that highlight the changes:

* [Bare function with a long signature](https://shiva.icesoldier.me/doc-custom/egg_mode/place/fn.reverse_geocode.html)
* [Struct methods, with single self argument and with self and non-self arguments](https://shiva.icesoldier.me/doc-custom/egg_mode/tweet/struct.Timeline.html#method.reset)
* [Bare functions with no arguments](https://shiva.icesoldier.me/doc-custom/rand/fn.thread_rng.html) and [struct methods with no arguments](https://shiva.icesoldier.me/doc-custom/hyper/client/struct.Client.html#method.new) are left unchanged.

This PR consists of two commits: one for bare functions and one for struct methods.
This commit is contained in:
Guillaume Gomez 2016-10-11 17:51:25 +02:00 committed by GitHub
commit 6717dba276
3 changed files with 356 additions and 102 deletions

View file

@ -1967,6 +1967,14 @@ fn item_function(w: &mut fmt::Formatter, cx: &Context, it: &clean::Item,
UnstableFeatures::Allow => f.constness,
_ => hir::Constness::NotConst
};
let prefix = format!("{}{}{}{:#}fn {}{:#}",
VisSpace(&it.visibility),
ConstnessSpace(vis_constness),
UnsafetySpace(f.unsafety),
AbiSpace(f.abi),
it.name.as_ref().unwrap(),
f.generics);
let indent = repeat("&nbsp;").take(prefix.len()).collect::<String>();
write!(w, "<pre class='rust fn'>{vis}{constness}{unsafety}{abi}fn \
{name}{generics}{decl}{where_clause}</pre>",
vis = VisSpace(&it.visibility),
@ -1976,7 +1984,7 @@ fn item_function(w: &mut fmt::Formatter, cx: &Context, it: &clean::Item,
name = it.name.as_ref().unwrap(),
generics = f.generics,
where_clause = WhereClause(&f.generics),
decl = f.decl)?;
decl = Method(&f.decl, &indent))?;
document(w, cx, it)
}
@ -2246,6 +2254,13 @@ fn render_assoc_item(w: &mut fmt::Formatter,
UnstableFeatures::Allow => constness,
_ => hir::Constness::NotConst
};
let prefix = format!("{}{}{:#}fn {}{:#}",
ConstnessSpace(vis_constness),
UnsafetySpace(unsafety),
AbiSpace(abi),
name,
*g);
let indent = repeat("&nbsp;").take(prefix.len()).collect::<String>();
write!(w, "{}{}{}fn <a href='{href}' class='fnname'>{name}</a>\
{generics}{decl}{where_clause}",
ConstnessSpace(vis_constness),
@ -2254,7 +2269,7 @@ fn render_assoc_item(w: &mut fmt::Formatter,
href = href,
name = name,
generics = *g,
decl = Method(d),
decl = Method(d, &indent),
where_clause = WhereClause(g))
}
match item.inner {