mikros/rust
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Rollup merge of #33867 - oli-obk:rustdoc_variant_types, r=GuillaumeGomez

Browse Source 
print enum variant fields in docs

Right now we are repeating enum variants at the top, because the fields aren't shown with the actual docs. It's very annoying to have to scroll up and down to have both docs and field info. For struct variants we already list the fields.

enum docs look like this after this PR:

![screenshot from 2016-05-25 14-02-42](https://cloud.githubusercontent.com/assets/332036/15539231/84b018cc-2281-11e6-9666-1063655931f4.png)

There are degenerate cases for enum tuple variants with lots of fields:

![screenshot from 2016-05-25 14-01-00](https://cloud.githubusercontent.com/assets/332036/15539260/91e537ca-2281-11e6-8bf1-a3d6b2e78f65.png)

I was thinking that we could move the docs below the variant (slightly indented) or list the variant fields vertically instead of horizontally

r? @steveklabnik
This commit is contained in:
Manish Goregaokar 2016-05-30 20:35:46 +05:30
commit 653ce3e525
4 changed files with 65 additions and 40 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
src/etc/htmldocck.py
View File

@ -117,6 +117,7 @@ from xml.etree import cElementTree as ET
from htmlentitydefs import entitydefs
entitydefs['larrb'] = u'\u21e4'
entitydefs['rarrb'] = u'\u21e5'
entitydefs['nbsp'] = ' '
# "void elements" (no closing tag) from the HTML Standard section 12.1.2
VOID_ELEMENTS = set(['area', 'base', 'br', 'col', 'embed', 'hr', 'img', 'input', 'keygen',

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

@ -111,27 +111,27 @@ impl fmt::Display for clean::Generics {
for (i, life) in self.lifetimes.iter().enumerate() {
if i > 0 {
f.write_str(", ")?;
f.write_str(", ")?;
}
write!(f, "{}", *life)?;
}
if !self.type_params.is_empty() {
if !self.lifetimes.is_empty() {
f.write_str(", ")?;
f.write_str(", ")?;
}
for (i, tp) in self.type_params.iter().enumerate() {
if i > 0 {
f.write_str(", ")?
f.write_str(", ")?
}
f.write_str(&tp.name)?;
if !tp.bounds.is_empty() {
write!(f, ": {}", TyParamBounds(&tp.bounds))?;
write!(f, ": {}", TyParamBounds(&tp.bounds))?;
}
match tp.default {
Some(ref ty) => { write!(f, " = {}", ty)?; },
Some(ref ty) => { write!(f, " = {}", ty)?; },
None => {}
};
}
@ -229,21 +229,21 @@ impl fmt::Display for clean::PathParameters {
let mut comma = false;
for lifetime in lifetimes {
if comma {
f.write_str(", ")?;
f.write_str(", ")?;
}
comma = true;
write!(f, "{}", *lifetime)?;
}
for ty in types {
if comma {
f.write_str(", ")?;
f.write_str(", ")?;
}
comma = true;
write!(f, "{}", *ty)?;
}
for binding in bindings {
if comma {
f.write_str(", ")?;
f.write_str(", ")?;
}
comma = true;
write!(f, "{}", *binding)?;

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

@ -2243,26 +2243,24 @@ fn item_struct(w: &mut fmt::Formatter, cx: &Context, it: &clean::Item,
write!(w, "</pre>")?;
document(w, cx, it)?;
let mut fields = s.fields.iter().filter(|f| {
let mut fields = s.fields.iter().filter_map(|f| {
match f.inner {
clean::StructFieldItem(..) => true,
_ => false,
clean::StructFieldItem(ref ty) => Some((f, ty)),
_ => None,
}
}).peekable();
if let doctree::Plain = s.struct_type {
if fields.peek().is_some() {
write!(w, "<h2 class='fields'>Fields</h2>\n<table>")?;
for field in fields {
write!(w, "<tr class='stab {stab}'>
<td id='{shortty}.{name}'>\
<code>{name}</code></td><td>",
write!(w, "<h2 class='fields'>Fields</h2>")?;
for (field, ty) in fields {
write!(w, "<span id='{shortty}.{name}'><code>{name}: {ty}</code></span>
<span class='stab {stab}'></span>",
shortty = ItemType::StructField,
stab = field.stability_class(),
name = field.name.as_ref().unwrap())?;
name = field.name.as_ref().unwrap(),
ty = ty)?;
document(w, cx, field)?;
write!(w, "</td></tr>")?;
}
write!(w, "</table>")?;
}
}
render_assoc_items(w, cx, it, it.def_id, AssocItemRender::All)
@ -2292,7 +2290,7 @@ fn item_enum(w: &mut fmt::Formatter, cx: &Context, it: &clean::Item,
write!(w, "{}(", name)?;
for (i, ty) in tys.iter().enumerate() {
if i > 0 {
write!(w, ", ")?
write!(w, ",&nbsp;")?
}
write!(w, "{}", *ty)?;
}
@ -2324,40 +2322,47 @@ fn item_enum(w: &mut fmt::Formatter, cx: &Context, it: &clean::Item,
document(w, cx, it)?;
if !e.variants.is_empty() {
write!(w, "<h2 class='variants'>Variants</h2>\n<table class='variants_table'>")?;
write!(w, "<h2 class='variants'>Variants</h2>\n")?;
for variant in &e.variants {
write!(w, "<tr><td id='{shortty}.{name}'><code>{name}</code></td><td>",
write!(w, "<span id='{shortty}.{name}' class='variant'><code>{name}",
shortty = ItemType::Variant,
name = variant.name.as_ref().unwrap())?;
if let clean::VariantItem(ref var) = variant.inner {
if let clean::TupleVariant(ref tys) = var.kind {
write!(w, "(")?;
for (i, ty) in tys.iter().enumerate() {
if i > 0 {
write!(w, ",&nbsp;")?;
}
write!(w, "{}", *ty)?;
}
write!(w, ")")?;
}
}
write!(w, "</code></span>")?;
document(w, cx, variant)?;
use clean::{Variant, StructVariant};
if let clean::VariantItem( Variant { kind: StructVariant(ref s) } ) = variant.inner {
let fields = s.fields.iter().filter(|f| {
match f.inner {
clean::StructFieldItem(..) => true,
_ => false,
}
});
write!(w, "<h3 class='fields'>Fields</h3>\n
<table>")?;
for field in fields {
write!(w, "<tr><td \
id='{shortty}.{v}.field.{f}'>\
<code>{f}</code></td><td>",
shortty = ItemType::Variant,
v = variant.name.as_ref().unwrap(),
f = field.name.as_ref().unwrap())?;
document(w, cx, field)?;
write!(w, "</td></tr>")?;
for field in &s.fields {
use clean::StructFieldItem;
if let StructFieldItem(ref ty) = field.inner {
write!(w, "<tr><td \
id='variant.{v}.field.{f}'>\
<code>{f}:&nbsp;{t}</code></td><td>",
v = variant.name.as_ref().unwrap(),
f = field.name.as_ref().unwrap(),
t = *ty)?;
document(w, cx, field)?;
write!(w, "</td></tr>")?;
}
}
write!(w, "</table>")?;
}
write!(w, "</td><td>")?;
render_stability_since(w, variant, it)?;
write!(w, "</td></tr>")?;
}
write!(w, "</table>")?;
}
render_assoc_items(w, cx, it, it.def_id, AssocItemRender::All)?;
Ok(())

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

@ -265,6 +265,10 @@ nav.sub {
.docblock h2 { font-size: 1.15em; }
.docblock h3, .docblock h4, .docblock h5 { font-size: 1em; }
.docblock {
margin-left: 24px;
}
.content .out-of-band {
font-size: 23px;
margin: 0px;
@ -640,6 +644,21 @@ span.since {
margin-right: 5px;
}
.enum > .toggle-wrapper > .collapse-toggle, .struct > .toggle-wrapper > .collapse-toggle {
left: 0;
margin-top: 5px;
}
.enum > .toggle-wrapper + .docblock, .struct > .toggle-wrapper + .docblock {
margin-left: 30px;
margin-bottom: 20px;
margin-top: 5px;
}
.enum > .collapsed, .struct > .collapsed {
margin-bottom: 25px;
}
:target > code {
background: #FDFFD3;
}