diff --git a/src/librustc_trans/save/mod.rs b/src/librustc_trans/save/mod.rs
index 1b9976be72f42..c5c4a75ef823b 100644
--- a/src/librustc_trans/save/mod.rs
+++ b/src/librustc_trans/save/mod.rs
@@ -42,13 +42,16 @@ pub struct CrateData {
     pub number: u32,
 }
 
-// Data for any entity in the Rust language. The actual data contained varied
-// with the kind of entity being queried. See the nested structs for details.
+/// Data for any entity in the Rust language. The actual data contained varied
+/// with the kind of entity being queried. See the nested structs for details.
 pub enum Data {
+    /// Data for all kinds of functions and methods.
     FunctionData(FunctionData),
+    /// Data for local and global variables (consts and statics).
     VariableData(VariableData),
 }
 
+/// Data for all kinds of functions and methods.
 pub struct FunctionData {
     pub id: NodeId,
     pub name: String,
@@ -58,6 +61,7 @@ pub struct FunctionData {
     pub scope: NodeId,
 }
 
+/// Data for local and global variables (consts and statics).
 pub struct VariableData {
     pub id: NodeId,
     pub name: String,
diff --git a/src/librustc_trans/save/span_utils.rs b/src/librustc_trans/save/span_utils.rs
index ba027e4c2d192..c3ac805af27ec 100644
--- a/src/librustc_trans/save/span_utils.rs
+++ b/src/librustc_trans/save/span_utils.rs
@@ -230,8 +230,8 @@ impl<'a> SpanUtils<'a> {
     // Reparse span and return an owned vector of sub spans of the first limit
     // identifier tokens in the given nesting level.
     // example with Foo<Bar<T,V>, Bar<T,V>>
-    // Nesting = 0: all idents outside of brackets: Vec<Foo>
-    // Nesting = 1: idents within one level of brackets: Vec<Bar, Bar>
+    // Nesting = 0: all idents outside of brackets: [Foo]
+    // Nesting = 1: idents within one level of brackets: [Bar, Bar]
     pub fn spans_with_brackets(&self, span: Span, nesting: isize, limit: isize) -> Vec<Span> {
         let mut result: Vec<Span> = vec!();
 
@@ -260,10 +260,20 @@ impl<'a> SpanUtils<'a> {
                 token::BinOp(token::Shr) => -2,
                 _ => 0
             };
+
             // Ignore the `>::` in `<Type as Trait>::AssocTy`.
+
+            // The root cause of this hack is that the AST representation of
+            // qpaths is horrible. It treats <A as B>::C as a path with two
+            // segments, B and C and notes that there is also a self type A at
+            // position 0. Because we don't have spans for individual idents,
+            // only the whole path, we have to iterate over the tokens in the
+            // path, trying to pull out the non-nested idents (e.g., avoiding 'a
+            // in `<A as B<'a>>::C`). So we end up with a span for `B>::C` from
+            // the start of the first ident to the end of the path.
             if !found_ufcs_sep && bracket_count == -1 {
                 found_ufcs_sep = true;
-                bracket_count += 1
+                bracket_count += 1;
             }
             if ts.tok.is_ident() && bracket_count == nesting {
                 result.push(self.make_sub_span(span, Some(ts.sp)).unwrap());
@@ -332,7 +342,7 @@ impl<'a> SpanUtils<'a> {
     }
 
 
-    // Returns a list of the spans of idents in a patch.
+    // Returns a list of the spans of idents in a path.
     // E.g., For foo::bar<x,t>::baz, we return [foo, bar, baz] (well, their spans)
     pub fn spans_for_path_segments(&self, path: &ast::Path) -> Vec<Span> {
         if generated_code(path.span) {