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

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

Author: Manishearth

src/etc/htmldocck.py

@@ -117,6 +117,7 @@
 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',

src/librustdoc/html/format.rs

@@ -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)?;

src/librustdoc/html/render.rs

@@ -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(())

src/librustdoc/html/static/rustdoc.css

@@ -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;
 }