Add comments and simplify MIR graphviz code.

Author: solson

src/librustc/mir/repr.rs

@@ -344,6 +344,9 @@ impl<'tcx> Debug for Terminator<'tcx> {
 }
 
 impl<'tcx> Terminator<'tcx> {
+    /// Write the "head" part of the terminator; that is, its name and the data it uses to pick the
+    /// successor basic block, if any. The only information not inlcuded is the list of possible
+    /// successors, which may be rendered differently between the text and the graphviz format.
     pub fn fmt_head<W: Write>(&self, fmt: &mut W) -> Result<(), Error> {
         use self::Terminator::*;
         match *self {
@@ -367,6 +370,7 @@ impl<'tcx> Terminator<'tcx> {
         }
     }
 
+    /// Return the list of labels for the edges to the successor basic blocks.
     pub fn fmt_successor_labels(&self) -> Vec<Cow<'static, str>> {
         use self::Terminator::*;
         match *self {
@@ -783,6 +787,7 @@ impl<'tcx> Debug for Literal<'tcx> {
     }
 }
 
+/// Write a `ConstVal` in a way closer to the original source code than the `Debug` output.
 pub fn fmt_const_val<W: Write>(fmt: &mut W, const_val: &ConstVal) -> Result<(), Error> {
     use middle::const_eval::ConstVal::*;
     match *const_val {

src/librustc_mir/graphviz.rs

@@ -11,15 +11,17 @@
 use dot;
 use rustc::mir::repr::*;
 use rustc::middle::ty;
+use std::fmt::Debug;
 use std::io::{self, Write};
 
+/// Write a graphviz DOT graph for the given MIR.
 pub fn write_mir_graphviz<W: Write>(mir: &Mir, w: &mut W) -> io::Result<()> {
     try!(writeln!(w, "digraph Mir {{"));
 
     // Global graph properties
-    try!(writeln!(w, r#"graph [fontname="monospace"];"#));
-    try!(writeln!(w, r#"node [fontname="monospace"];"#));
-    try!(writeln!(w, r#"edge [fontname="monospace"];"#));
+    try!(writeln!(w, r#"    graph [fontname="monospace"];"#));
+    try!(writeln!(w, r#"    node [fontname="monospace"];"#));
+    try!(writeln!(w, r#"    edge [fontname="monospace"];"#));
 
     // Graph label
     try!(write_graph_label(mir, w));
@@ -37,84 +39,93 @@ pub fn write_mir_graphviz<W: Write>(mir: &Mir, w: &mut W) -> io::Result<()> {
     writeln!(w, "}}")
 }
 
+/// Write a graphviz DOT node for the given basic block.
 fn write_node<W: Write>(block: BasicBlock, mir: &Mir, w: &mut W) -> io::Result<()> {
     let data = mir.basic_block_data(block);
 
-    try!(write!(w, r#"bb{} [shape="none", label=<"#, block.index()));
+    // Start a new node with the label to follow, in one of DOT's pseudo-HTML tables.
+    try!(write!(w, r#"    {} [shape="none", label=<"#, node(block)));
     try!(write!(w, r#"<table border="0" cellborder="1" cellspacing="0">"#));
 
-    try!(write!(w, r#"<tr><td bgcolor="gray" align="center">"#));
-    try!(write!(w, "{}", block.index()));
-    try!(write!(w, "</td></tr>"));
+    // Basic block number at the top.
+    try!(write!(w, r#"<tr><td bgcolor="gray" align="center">{}</td></tr>"#, block.index()));
 
+    // List of statements in the middle.
     if !data.statements.is_empty() {
         try!(write!(w, r#"<tr><td align="left" balign="left">"#));
         for statement in &data.statements {
-            try!(write!(w, "{}", dot::escape_html(&format!("{:?}", statement))));
-            try!(write!(w, "<br/>"));
+            try!(write!(w, "{}<br/>", escape(statement)));
         }
         try!(write!(w, "</td></tr>"));
     }
 
-    try!(write!(w, r#"<tr><td align="left">"#));
-
+    // Terminator head at the bottom, not including the list of successor blocks. Those will be
+    // displayed as labels on the edges between blocks.
     let mut terminator_head = String::new();
     data.terminator.fmt_head(&mut terminator_head).unwrap();
-    try!(write!(w, "{}", dot::escape_html(&terminator_head)));
-    try!(write!(w, "</td></tr>"));
+    try!(write!(w, r#"<tr><td align="left">{}</td></tr>"#, dot::escape_html(&terminator_head)));
 
-    try!(write!(w, "</table>"));
-    writeln!(w, ">];")
+    // Close the table, node label, and the node itself.
+    writeln!(w, "</table>>];")
 }
 
+/// Write graphviz DOT edges with labels between the given basic block and all of its successors.
 fn write_edges<W: Write>(source: BasicBlock, mir: &Mir, w: &mut W) -> io::Result<()> {
     let terminator = &mir.basic_block_data(source).terminator;
     let labels = terminator.fmt_successor_labels();
 
-    for (i, target) in terminator.successors().into_iter().enumerate() {
-        try!(write!(w, "bb{} -> bb{}", source.index(), target.index()));
-        try!(writeln!(w, r#" [label="{}"];"#, labels[i]));
+    for (&target, label) in terminator.successors().iter().zip(labels) {
+        try!(writeln!(w, r#"    {} -> {} [label="{}"];"#, node(source), node(target), label));
     }
 
     Ok(())
 }
 
+/// Write the graphviz DOT label for the overall graph. This is essentially a block of text that
+/// will appear below the graph, showing the type of the `fn` this MIR represents and the types of
+/// all the variables and temporaries.
 fn write_graph_label<W: Write>(mir: &Mir, w: &mut W) -> io::Result<()> {
-    try!(write!(w, "label=<"));
-    try!(write!(w, "fn("));
+    try!(write!(w, "    label=<fn("));
 
+    // fn argument types.
     for (i, arg) in mir.arg_decls.iter().enumerate() {
         if i > 0 {
             try!(write!(w, ", "));
         }
-        try!(write!(w, "{}", dot::escape_html(&format!("a{}: {:?}", i, arg.ty))));
+        try!(write!(w, "a{}: {}", i, escape(&arg.ty)));
     }
 
-    try!(write!(w, "{}", dot::escape_html(") -> ")));
+    try!(write!(w, ") -&gt; "));
 
+    // fn return type.
     match mir.return_ty {
-        ty::FnOutput::FnConverging(ty) =>
-            try!(write!(w, "{}", dot::escape_html(&format!("{:?}", ty)))),
-        ty::FnOutput::FnDiverging =>
-            try!(write!(w, "{}", dot::escape_html("!"))),
+        ty::FnOutput::FnConverging(ty) => try!(write!(w, "{}", escape(ty))),
+        ty::FnOutput::FnDiverging => try!(write!(w, "!")),
     }
 
     try!(write!(w, r#"<br align="left"/>"#));
 
+    // User variable types (including the user's name in a comment).
     for (i, var) in mir.var_decls.iter().enumerate() {
         try!(write!(w, "let "));
         if var.mutability == Mutability::Mut {
             try!(write!(w, "mut "));
         }
-        let text = format!("v{}: {:?}; // {}", i, var.ty, var.name);
-        try!(write!(w, "{}", dot::escape_html(&text)));
-        try!(write!(w, r#"<br align="left"/>"#));
+        try!(write!(w, r#"v{}: {}; // {}<br align="left"/>"#, i, escape(&var.ty), var.name));
     }
 
+    // Compiler-introduced temporary types.
     for (i, temp) in mir.temp_decls.iter().enumerate() {
-        try!(write!(w, "{}", dot::escape_html(&format!("let t{}: {:?};", i, temp.ty))));
-        try!(write!(w, r#"<br align="left"/>"#));
+        try!(write!(w, r#"let t{}: {};<br align="left"/>"#, i, escape(&temp.ty)));
     }
 
     writeln!(w, ">;")
 }
+
+fn node(block: BasicBlock) -> String {
+    format!("bb{}", block.index())
+}
+
+fn escape<T: Debug>(t: &T) -> String {
+    dot::escape_html(&format!("{:?}", t))
+}