Various minor/cosmetic improvements to code

3 files changed, 112 insertions, 109 deletions

diff --git a/src/libsyntax_pos/hygiene.rs b/src/libsyntax_pos/hygiene.rs
index 074687fc726..74f63b5e2c6 100644
--- a/src/libsyntax_pos/hygiene.rs
+++ b/src/libsyntax_pos/hygiene.rs
@@ -308,11 +308,11 @@ impl SyntaxContext {
         }
 
         // Otherwise, `mark` is a macros 1.0 definition and the call site is in a
-        // macros 2.0 expansion, i.e. a macros 1.0 invocation is in a macros 2.0 definition.
+        // macros 2.0 expansion, i.e., a macros 1.0 invocation is in a macros 2.0 definition.
         //
         // In this case, the tokens from the macros 1.0 definition inherit the hygiene
         // at their invocation. That is, we pretend that the macros 1.0 definition
-        // was defined at its invocation (i.e. inside the macros 2.0 definition)
+        // was defined at its invocation (i.e., inside the macros 2.0 definition)
         // so that the macros 2.0 definition remains hygienic.
         //
         // See the example at `test/run-pass/hygiene/legacy_interaction.rs`.
@@ -438,7 +438,7 @@ impl SyntaxContext {
     /// }
     /// ```
     /// This returns the expansion whose definition scope we use to privacy check the resolution,
-    /// or `None` if we privacy check as usual (i.e. not w.r.t. a macro definition scope).
+    /// or `None` if we privacy check as usual (i.e., not w.r.t. a macro definition scope).
     pub fn adjust(&mut self, expansion: Mark) -> Option<Mark> {
         let mut scope = None;
         while !expansion.is_descendant_of(self.outer()) {
@@ -540,7 +540,7 @@ pub struct ExpnInfo {
     /// The location of the actual macro invocation or syntax sugar , e.g.
     /// `let x = foo!();` or `if let Some(y) = x {}`
     ///
-    /// This may recursively refer to other macro invocations, e.g. if
+    /// This may recursively refer to other macro invocations, e.g., if
     /// `foo!()` invoked `bar!()` internally, and there was an
     /// expression inside `bar!`; the call_site of the expression in
     /// the expansion would point to the `bar!` invocation; that
@@ -548,7 +548,7 @@ pub struct ExpnInfo {
     /// pointing to the `foo!` invocation.
     pub call_site: Span,
     /// The span of the macro definition itself. The macro may not
-    /// have a sensible definition span (e.g. something defined
+    /// have a sensible definition span (e.g., something defined
     /// completely inside libsyntax) in which case this is None.
     /// This span serves only informational purpose and is not used for resolution.
     pub def_site: Option<Span>,
@@ -571,9 +571,9 @@ pub struct ExpnInfo {
 /// The source of expansion.
 #[derive(Clone, Hash, Debug, PartialEq, Eq, RustcEncodable, RustcDecodable)]
 pub enum ExpnFormat {
-    /// e.g. #[derive(...)] <item>
+    /// e.g., #[derive(...)] <item>
     MacroAttribute(Symbol),
-    /// e.g. `format!()`
+    /// e.g., `format!()`
     MacroBang(Symbol),
     /// Desugaring done by the compiler during HIR lowering.
     CompilerDesugaring(CompilerDesugaringKind)
diff --git a/src/libsyntax_pos/lib.rs b/src/libsyntax_pos/lib.rs
index 4e3d1e89a72..8b7ffa499cd 100644
--- a/src/libsyntax_pos/lib.rs
+++ b/src/libsyntax_pos/lib.rs
@@ -8,9 +8,9 @@
 // option. This file may not be copied, modified, or distributed
 // except according to those terms.
 
-//! The source positions and related helper functions
+//! The source positions and related helper functions.
 //!
-//! # Note
+//! ## Note
 //!
 //! This API is completely unstable and subject to change.
 
@@ -27,17 +27,6 @@
 #![feature(specialization)]
 #![cfg_attr(not(stage0), feature(stdsimd))]
 
-use std::borrow::Cow;
-use std::cell::Cell;
-use std::cmp::{self, Ordering};
-use std::fmt;
-use std::hash::{Hasher, Hash};
-use std::ops::{Add, Sub};
-use std::path::PathBuf;
-
-use rustc_data_structures::stable_hasher::StableHasher;
-use rustc_data_structures::sync::{Lrc, Lock};
-
 extern crate arena;
 extern crate rustc_data_structures;
 
@@ -65,6 +54,17 @@ pub mod symbol;
 
 mod analyze_source_file;
 
+use rustc_data_structures::stable_hasher::StableHasher;
+use rustc_data_structures::sync::{Lrc, Lock};
+
+use std::borrow::Cow;
+use std::cell::Cell;
+use std::cmp::{self, Ordering};
+use std::fmt;
+use std::hash::{Hasher, Hash};
+use std::ops::{Add, Sub};
+use std::path::PathBuf;
+
 pub struct Globals {
     symbol_interner: Lock<symbol::Interner>,
     span_interner: Lock<span_encoding::SpanInterner>,
@@ -83,25 +83,25 @@ impl Globals {
 
 scoped_thread_local!(pub static GLOBALS: Globals);
 
-/// Differentiates between real files and common virtual files
+/// Differentiates between real files and common virtual files.
 #[derive(Debug, Eq, PartialEq, Clone, Ord, PartialOrd, Hash, RustcDecodable, RustcEncodable)]
 pub enum FileName {
     Real(PathBuf),
     /// A macro.  This includes the full name of the macro, so that there are no clashes.
     Macros(String),
-    /// call to `quote!`
+    /// Call to `quote!`.
     QuoteExpansion(u64),
-    /// Command line
+    /// Command line.
     Anon(u64),
-    /// Hack in src/libsyntax/parse.rs
-    /// FIXME(jseyfried)
+    /// Hack in `src/libsyntax/parse.rs`.
+    // FIXME(jseyfried)
     MacroExpansion(u64),
     ProcMacroSourceCode(u64),
-    /// Strings provided as --cfg [cfgspec] stored in a crate_cfg
+    /// Strings provided as `--cfg [cfgspec]` stored in a `crate_cfg`.
     CfgSpec(u64),
-    /// Strings provided as crate attributes in the CLI
+    /// Strings provided as crate attributes in the CLI.
     CliCrateAttr(u64),
-    /// Custom sources for explicit parser calls from plugins and drivers
+    /// Custom sources for explicit parser calls from plugins and drivers.
     Custom(String),
     DocTest(PathBuf, isize),
 }
@@ -208,11 +208,11 @@ impl FileName {
 
 /// Spans represent a region of code, used for error reporting. Positions in spans
 /// are *absolute* positions from the beginning of the source_map, not positions
-/// relative to SourceFiles. Methods on the SourceMap can be used to relate spans back
+/// relative to `SourceFile`s. Methods on the `SourceMap` can be used to relate spans back
 /// to the original source.
 /// You must be careful if the span crosses more than one file - you will not be
 /// able to use many of the functions on spans in source_map and you cannot assume
-/// that the length of the span = hi - lo; there may be space in the BytePos
+/// that the length of the `span = hi - lo`; there may be space in the `BytePos`
 /// range between files.
 ///
 /// `SpanData` is public because `Span` uses a thread-local interner and can't be
@@ -243,7 +243,7 @@ impl SpanData {
 }
 
 // The interner is pointed to by a thread local value which is only set on the main thread
-// with parallelization is disabled. So we don't allow Span to transfer between threads
+// with parallelization is disabled. So we don't allow `Span` to transfer between threads
 // to avoid panics and other errors, even though it would be memory safe to do so.
 #[cfg(not(parallel_queries))]
 impl !Send for Span {}
@@ -263,9 +263,9 @@ impl Ord for Span {
 
 /// A collection of spans. Spans have two orthogonal attributes:
 ///
-/// - they can be *primary spans*. In this case they are the locus of
+/// - They can be *primary spans*. In this case they are the locus of
 ///   the error, and would be rendered with `^^^`.
-/// - they can have a *label*. In this case, the label is written next
+/// - They can have a *label*. In this case, the label is written next
 ///   to the mark in the snippet when we render.
 #[derive(Clone, Debug, Hash, PartialEq, Eq, RustcEncodable, RustcDecodable)]
 pub struct MultiSpan {
@@ -312,7 +312,7 @@ impl Span {
         let span = self.data();
         span.with_hi(span.lo)
     }
-    /// Returns a new span representing an empty span at the end of this span
+    /// Returns a new span representing an empty span at the end of this span.
     #[inline]
     pub fn shrink_to_hi(self) -> Span {
         let span = self.data();
@@ -324,7 +324,7 @@ impl Span {
         if self.is_dummy() { other } else { self }
     }
 
-    /// Return true if `self` fully encloses `other`.
+    /// Return `true` if `self` fully encloses `other`.
     pub fn contains(self, other: Span) -> bool {
         let span = self.data();
         let other = other.data();
@@ -341,7 +341,7 @@ impl Span {
         span.lo == other.lo && span.hi == other.hi
     }
 
-    /// Returns `Some(span)`, where the start is trimmed by the end of `other`
+    /// Returns `Some(span)`, where the start is trimmed by the end of `other`.
     pub fn trim_start(self, other: Span) -> Option<Span> {
         let span = self.data();
         let other = other.data();
@@ -352,14 +352,14 @@ impl Span {
         }
     }
 
-    /// Return the source span - this is either the supplied span, or the span for
+    /// Return the source span -- this is either the supplied span, or the span for
     /// the macro callsite that expanded to it.
     pub fn source_callsite(self) -> Span {
         self.ctxt().outer().expn_info().map(|info| info.call_site.source_callsite()).unwrap_or(self)
     }
 
     /// The `Span` for the tokens in the previous macro expansion from which `self` was generated,
-    /// if any
+    /// if any.
     pub fn parent(self) -> Option<Span> {
         self.ctxt().outer().expn_info().map(|i| i.call_site)
     }
@@ -395,7 +395,7 @@ impl Span {
         self.ctxt().outer().expn_info().map(source_callee)
     }
 
-    /// Check if a span is "internal" to a macro in which #[unstable]
+    /// Check if a span is "internal" to a macro in which `#[unstable]`
     /// items can be used (that is, a macro marked with
     /// `#[allow_internal_unstable]`).
     pub fn allows_unstable(&self) -> bool {
@@ -416,7 +416,7 @@ impl Span {
         }
     }
 
-    /// Return the compiler desugaring that created this span, or None
+    /// Return the compiler desugaring that created this span, or `None`
     /// if this span is not from a desugaring.
     pub fn compiler_desugaring_kind(&self) -> Option<CompilerDesugaringKind> {
         match self.ctxt().outer().expn_info() {
@@ -442,7 +442,7 @@ impl Span {
         let mut prev_span = DUMMY_SP;
         let mut result = vec![];
         while let Some(info) = self.ctxt().outer().expn_info() {
-            // Don't print recursive invocations
+            // Don't print recursive invocations.
             if !info.call_site.source_equal(&prev_span) {
                 let (pre, post) = match info.format {
                     ExpnFormat::MacroAttribute(..) => ("#[", "]"),
@@ -466,7 +466,7 @@ impl Span {
     pub fn to(self, end: Span) -> Span {
         let span_data = self.data();
         let end_data = end.data();
-        // FIXME(jseyfried): self.ctxt should always equal end.ctxt here (c.f. issue #23480)
+        // FIXME(jseyfried): `self.ctxt` should always equal `end.ctxt` here (cf. issue #23480).
         // Return the macro span on its own to avoid weird diagnostic output. It is preferable to
         // have an incomplete span than a completely nonsensical one.
         if span_data.ctxt != end_data.ctxt {
@@ -475,8 +475,8 @@ impl Span {
             } else if end_data.ctxt == SyntaxContext::empty() {
                 return self;
             }
-            // both span fall within a macro
-            // FIXME(estebank) check if it is the *same* macro
+            // Both spans fall within a macro.
+            // FIXME(estebank): check if it is the *same* macro.
         }
         Span::new(
             cmp::min(span_data.lo, end_data.lo),
@@ -658,7 +658,7 @@ impl MultiSpan {
         self.span_labels.push((span, label));
     }
 
-    /// Selects the first primary span (if any)
+    /// Selects the first primary span (if any).
     pub fn primary_span(&self) -> Option<Span> {
         self.primary_spans.first().cloned()
     }
@@ -679,7 +679,7 @@ impl MultiSpan {
         is_dummy
     }
 
-    /// Replaces all occurrences of one Span with another. Used to move Spans in areas that don't
+    /// Replaces all occurrences of one Span with another. Used to move `Span`s in areas that don't
     /// display well (like std macros). Returns true if replacements occurred.
     pub fn replace(&mut self, before: Span, after: Span) -> bool {
         let mut replacements_occurred = false;
@@ -700,7 +700,7 @@ impl MultiSpan {
 
     /// Returns the strings to highlight. We always ensure that there
     /// is an entry for each of the primary spans -- for each primary
-    /// span P, if there is at least one label with span P, we return
+    /// span `P`, if there is at least one label with span `P`, we return
     /// those labels (marked as primary). But otherwise we return
     /// `SpanLabel` instances with empty labels.
     pub fn span_labels(&self) -> Vec<SpanLabel> {
@@ -742,23 +742,23 @@ impl From<Vec<Span>> for MultiSpan {
 
 pub const NO_EXPANSION: SyntaxContext = SyntaxContext::empty();
 
-/// Identifies an offset of a multi-byte character in a SourceFile
+/// Identifies an offset of a multi-byte character in a `SourceFile`.
 #[derive(Copy, Clone, RustcEncodable, RustcDecodable, Eq, PartialEq, Debug)]
 pub struct MultiByteChar {
-    /// The absolute offset of the character in the SourceMap
+    /// The absolute offset of the character in the `SourceMap`.
     pub pos: BytePos,
-    /// The number of bytes, >=2
+    /// The number of bytes, `>= 2`.
     pub bytes: u8,
 }
 
-/// Identifies an offset of a non-narrow character in a SourceFile
+/// Identifies an offset of a non-narrow character in a `SourceFile`.
 #[derive(Copy, Clone, RustcEncodable, RustcDecodable, Eq, PartialEq, Debug)]
 pub enum NonNarrowChar {
-    /// Represents a zero-width character
+    /// Represents a zero-width character.
     ZeroWidth(BytePos),
-    /// Represents a wide (fullwidth) character
+    /// Represents a wide (full-width) character.
     Wide(BytePos),
-    /// Represents a tab character, represented visually with a width of 4 characters
+    /// Represents a tab character, represented visually with a width of 4 characters.
     Tab(BytePos),
 }
 
@@ -772,7 +772,7 @@ impl NonNarrowChar {
         }
     }
 
-    /// Returns the absolute offset of the character in the SourceMap
+    /// Returns the absolute offset of the character in the `SourceMap`.
     pub fn pos(&self) -> BytePos {
         match *self {
             NonNarrowChar::ZeroWidth(p) |
@@ -781,7 +781,7 @@ impl NonNarrowChar {
         }
     }
 
-    /// Returns the width of the character, 0 (zero-width) or 2 (wide)
+    /// Returns the width of the character, 0 (zero-width) or 2 (wide).
     pub fn width(&self) -> usize {
         match *self {
             NonNarrowChar::ZeroWidth(_) => 0,
@@ -815,7 +815,7 @@ impl Sub<BytePos> for NonNarrowChar {
     }
 }
 
-/// The state of the lazy external source loading mechanism of a SourceFile.
+/// The state of the lazy external source loading mechanism of a `SourceFile`.
 #[derive(PartialEq, Eq, Clone)]
 pub enum ExternalSource {
     /// The external source has been loaded already.
@@ -824,7 +824,7 @@ pub enum ExternalSource {
     AbsentOk,
     /// A failed attempt has been made to load the external source.
     AbsentErr,
-    /// No external source has to be loaded, since the SourceFile represents a local crate.
+    /// No external source has to be loaded, since the `SourceFile` represents a local crate.
     Unneeded,
 }
 
@@ -844,38 +844,38 @@ impl ExternalSource {
     }
 }
 
-/// A single source in the SourceMap.
+/// A single source in the `SourceMap`.
 #[derive(Clone)]
 pub struct SourceFile {
     /// The name of the file that the source came from, source that doesn't
-    /// originate from files has names between angle brackets by convention,
-    /// e.g. `<anon>`
+    /// originate from files has names between angle brackets by convention
+    /// (e.g., `<anon>`).
     pub name: FileName,
-    /// True if the `name` field above has been modified by --remap-path-prefix
+    /// True if the `name` field above has been modified by `--remap-path-prefix`.
     pub name_was_remapped: bool,
     /// The unmapped path of the file that the source came from.
-    /// Set to `None` if the SourceFile was imported from an external crate.
+    /// Set to `None` if the `SourceFile` was imported from an external crate.
     pub unmapped_path: Option<FileName>,
-    /// Indicates which crate this SourceFile was imported from.
+    /// Indicates which crate this `SourceFile` was imported from.
     pub crate_of_origin: u32,
-    /// The complete source code
+    /// The complete source code.
     pub src: Option<Lrc<String>>,
-    /// The source code's hash
+    /// The source code's hash.
     pub src_hash: u128,
     /// The external source code (used for external crates, which will have a `None`
     /// value as `self.src`.
     pub external_src: Lock<ExternalSource>,
-    /// The start position of this source in the SourceMap
+    /// The start position of this source in the `SourceMap`.
     pub start_pos: BytePos,
-    /// The end position of this source in the SourceMap
+    /// The end position of this source in the `SourceMap`.
     pub end_pos: BytePos,
-    /// Locations of lines beginnings in the source code
+    /// Locations of lines beginnings in the source code.
     pub lines: Vec<BytePos>,
-    /// Locations of multi-byte characters in the source code
+    /// Locations of multi-byte characters in the source code.
     pub multibyte_chars: Vec<MultiByteChar>,
-    /// Width of characters that are not narrow in the source code
+    /// Width of characters that are not narrow in the source code.
     pub non_narrow_chars: Vec<NonNarrowChar>,
-    /// A hash of the filename, used for speeding up the incr. comp. hashing.
+    /// A hash of the filename, used for speeding up hashing in incremental compilation.
     pub name_hash: u128,
 }
 
@@ -889,7 +889,7 @@ impl Encodable for SourceFile {
             s.emit_struct_field("end_pos", 5, |s| self.end_pos.encode(s))?;
             s.emit_struct_field("lines", 6, |s| {
                 let lines = &self.lines[..];
-                // store the length
+                // Store the length.
                 s.emit_u32(lines.len() as u32)?;
 
                 if !lines.is_empty() {
@@ -1060,7 +1060,7 @@ impl SourceFile {
         }
     }
 
-    /// Return the BytePos of the beginning of the current line.
+    /// Return the `BytePos` of the beginning of the current line.
     pub fn line_begin_pos(&self, pos: BytePos) -> BytePos {
         let line_index = self.lookup_line(pos).unwrap();
         self.lines[line_index]
@@ -1148,9 +1148,9 @@ impl SourceFile {
     }
 
     /// Find the line containing the given position. The return value is the
-    /// index into the `lines` array of this SourceFile, not the 1-based line
+    /// index into the `lines` array of this `SourceFile`, not the 1-based line
     /// number. If the source_file is empty or the position is located before the
-    /// first line, None is returned.
+    /// first line, `None` is returned.
     pub fn lookup_line(&self, pos: BytePos) -> Option<usize> {
         if self.lines.len() == 0 {
             return None;
@@ -1207,14 +1207,14 @@ pub trait Pos {
 #[derive(Clone, Copy, PartialEq, Eq, Hash, PartialOrd, Ord, Debug)]
 pub struct BytePos(pub u32);
 
-/// A character offset. Because of multibyte utf8 characters, a byte offset
-/// is not equivalent to a character offset. The SourceMap will convert BytePos
-/// values to CharPos values as necessary.
+/// A character offset. Because of multibyte UTF-8 characters, a byte offset
+/// is not equivalent to a character offset. The `SourceMap` will convert `BytePos`
+/// values to `CharPos` values as necessary.
 #[derive(Copy, Clone, PartialEq, Eq, Hash, PartialOrd, Ord, Debug)]
 pub struct CharPos(pub usize);
 
-// FIXME: Lots of boilerplate in these impls, but so far my attempts to fix
-// have been unsuccessful
+// FIXME: lots of boilerplate in these impls, but so far my attempts to fix
+// have been unsuccessful.
 
 impl Pos for BytePos {
     #[inline(always)]
@@ -1296,20 +1296,20 @@ impl Sub for CharPos {
 // Loc, LocWithOpt, SourceFileAndLine, SourceFileAndBytePos
 //
 
-/// A source code location used for error reporting
+/// A source code location used for error reporting.
 #[derive(Debug, Clone)]
 pub struct Loc {
-    /// Information about the original source
+    /// Information about the original source.
     pub file: Lrc<SourceFile>,
-    /// The (1-based) line number
+    /// The (1-based) line number.
     pub line: usize,
-    /// The (0-based) column offset
+    /// The (0-based) column offset.
     pub col: CharPos,
-    /// The (0-based) column offset when displayed
+    /// The (0-based) column offset when displayed.
     pub col_display: usize,
 }
 
-/// A source code location used as the result of lookup_char_pos_adj
+/// A source code location used as the result of `lookup_char_pos_adj`.
 // Actually, *none* of the clients use the filename *or* file field;
 // perhaps they should just be removed.
 #[derive(Debug)]
@@ -1320,7 +1320,7 @@ pub struct LocWithOpt {
     pub file: Option<Lrc<SourceFile>>,
 }
 
-// used to be structural records. Better names, anyone?
+// Used to be structural records.
 #[derive(Debug)]
 pub struct SourceFileAndLine { pub sf: Lrc<SourceFile>, pub line: usize }
 #[derive(Debug)]
diff --git a/src/libsyntax_pos/symbol.rs b/src/libsyntax_pos/symbol.rs
index 847bf60cefb..05c53878e70 100644
--- a/src/libsyntax_pos/symbol.rs
+++ b/src/libsyntax_pos/symbol.rs
@@ -9,20 +9,21 @@
 // except according to those terms.
 
 //! An "interner" is a data structure that associates values with usize tags and
-//! allows bidirectional lookup; i.e. given a value, one can easily find the
+//! allows bidirectional lookup; i.e., given a value, one can easily find the
 //! type, and vice versa.
 
-use hygiene::SyntaxContext;
-use {Span, DUMMY_SP, GLOBALS};
-
-use rustc_data_structures::fx::FxHashMap;
 use arena::DroplessArena;
+use rustc_data_structures::fx::FxHashMap;
 use serialize::{Decodable, Decoder, Encodable, Encoder};
+
 use std::fmt;
 use std::str;
 use std::cmp::{PartialEq, Ordering, PartialOrd, Ord};
 use std::hash::{Hash, Hasher};
 
+use hygiene::SyntaxContext;
+use {Span, DUMMY_SP, GLOBALS};
+
 #[derive(Copy, Clone, Eq)]
 pub struct Ident {
     pub name: Symbol,
@@ -34,6 +35,7 @@ impl Ident {
     pub const fn new(name: Symbol, span: Span) -> Ident {
         Ident { name, span }
     }
+
     #[inline]
     pub const fn with_empty_ctxt(name: Symbol) -> Ident {
         Ident::new(name, DUMMY_SP)
@@ -60,7 +62,7 @@ impl Ident {
 
     /// "Normalize" ident for use in comparisons using "item hygiene".
     /// Identifiers with same string value become same if they came from the same "modern" macro
-    /// (e.g. `macro` item, but not `macro_rules` item) and stay different if they came from
+    /// (e.g., `macro` item, but not `macro_rules` item) and stay different if they came from
     /// different "modern" macros.
     /// Technically, this operation strips all non-opaque marks from ident's syntactic context.
     pub fn modern(self) -> Ident {
@@ -69,7 +71,7 @@ impl Ident {
 
     /// "Normalize" ident for use in comparisons using "local variable hygiene".
     /// Identifiers with same string value become same if they came from the same non-transparent
-    /// macro (e.g. `macro` or `macro_rules!` items) and stay different if they came from different
+    /// macro (e.g., `macro` or `macro_rules!` items) and stay different if they came from different
     /// non-transparent macros.
     /// Technically, this operation strips all transparent marks from ident's syntactic context.
     pub fn modern_and_legacy(self) -> Ident {
@@ -122,7 +124,7 @@ impl Encodable for Ident {
     fn encode<S: Encoder>(&self, s: &mut S) -> Result<(), S::Error> {
         if self.span.ctxt().modern() == SyntaxContext::empty() {
             s.emit_str(&self.as_str())
-        } else { // FIXME(jseyfried) intercrate hygiene
+        } else { // FIXME(jseyfried): intercrate hygiene
             let mut string = "#".to_owned();
             string.push_str(&self.as_str());
             s.emit_str(&string)
@@ -135,7 +137,7 @@ impl Decodable for Ident {
         let string = d.read_str()?;
         Ok(if !string.starts_with('#') {
             Ident::from_str(&string)
-        } else { // FIXME(jseyfried) intercrate hygiene
+        } else { // FIXME(jseyfried): intercrate hygiene
             Ident::with_empty_ctxt(Symbol::gensym(&string[1..]))
         })
     }
@@ -146,7 +148,7 @@ impl Decodable for Ident {
 pub struct Symbol(u32);
 
 // The interner is pointed to by a thread local value which is only set on the main thread
-// with parallelization is disabled. So we don't allow Symbol to transfer between threads
+// with parallelization is disabled. So we don't allow `Symbol` to transfer between threads
 // to avoid panics and other errors, even though it would be memory safe to do so.
 #[cfg(not(parallel_queries))]
 impl !Send for Symbol { }
@@ -163,7 +165,7 @@ impl Symbol {
         with_interner(|interner| interner.interned(self))
     }
 
-    /// gensym's a new usize, using the current interner.
+    /// Gensyms a new usize, using the current interner.
     pub fn gensym(string: &str) -> Self {
         with_interner(|interner| interner.gensym(string))
     }
@@ -226,7 +228,7 @@ impl<T: ::std::ops::Deref<Target=str>> PartialEq<T> for Symbol {
     }
 }
 
-// The &'static strs in this type actually point into the arena
+// The `&'static str`s in this type actually point into the arena.
 #[derive(Default)]
 pub struct Interner {
     arena: DroplessArena,
@@ -240,7 +242,7 @@ impl Interner {
         let mut this = Interner::default();
         for &string in init {
             if string == "" {
-                // We can't allocate empty strings in the arena, so handle this here
+                // We can't allocate empty strings in the arena, so handle this here.
                 let name = Symbol(this.strings.len() as u32);
                 this.names.insert("", name);
                 this.strings.push("");
@@ -258,12 +260,13 @@ impl Interner {
 
         let name = Symbol(self.strings.len() as u32);
 
-        // from_utf8_unchecked is safe since we just allocated a &str which is known to be utf8
+        // `from_utf8_unchecked` is safe since we just allocated a `&str` which is known to be
+        // UTF-8.
         let string: &str = unsafe {
             str::from_utf8_unchecked(self.arena.alloc_slice(string.as_bytes()))
         };
-        // It is safe to extend the arena allocation to 'static because we only access
-        // these while the arena is still alive
+        // It is safe to extend the arena allocation to `'static` because we only access
+        // these while the arena is still alive.
         let string: &'static str =  unsafe {
             &*(string as *const str)
         };
@@ -344,7 +347,7 @@ macro_rules! declare_keywords {(
     }
 }}
 
-// NB: leaving holes in the ident table is bad! a different ident will get
+// N.B., leaving holes in the ident table is bad! a different ident will get
 // interned with the id from the hole, but it will be between the min and max
 // of the reserved words, and thus tagged as "reserved".
 // After modifying this list adjust `is_special`, `is_used_keyword`/`is_unused_keyword`,
@@ -438,7 +441,7 @@ impl Symbol {
 }
 
 impl Ident {
-    // Returns true for reserved identifiers used internally for elided lifetimes,
+    // Returns `true` for reserved identifiers used internally for elided lifetimes,
     // unnamed method parameters, crate root module, error recovery etc.
     pub fn is_special(self) -> bool {
         self.name <= keywords::Underscore.name()
@@ -491,8 +494,8 @@ fn with_interner<T, F: FnOnce(&mut Interner) -> T>(f: F) -> T {
 /// Represents a string stored in the interner. Because the interner outlives any thread
 /// which uses this type, we can safely treat `string` which points to interner data,
 /// as an immortal string, as long as this type never crosses between threads.
-// FIXME: Ensure that the interner outlives any thread which uses LocalInternedString,
-//        by creating a new thread right after constructing the interner
+// FIXME: ensure that the interner outlives any thread which uses `LocalInternedString`,
+// by creating a new thread right after constructing the interner.
 #[derive(Clone, Copy, Hash, PartialOrd, Eq, Ord)]
 pub struct LocalInternedString {
     string: &'static str,
@@ -581,7 +584,7 @@ impl Encodable for LocalInternedString {
     }
 }
 
-/// Represents a string stored in the string interner
+/// Represents a string stored in the string interner.
 #[derive(Clone, Copy, Eq)]
 pub struct InternedString {
     symbol: Symbol,