diff --git a/src/librustc/middle/infer/higher_ranked/mod.rs b/src/librustc/middle/infer/higher_ranked/mod.rs
index 4469e27a5b05..ea59446c6d5b 100644
--- a/src/librustc/middle/infer/higher_ranked/mod.rs
+++ b/src/librustc/middle/infer/higher_ranked/mod.rs
@@ -465,7 +465,8 @@ pub fn skolemize_late_bound_regions<'a,'tcx,T>(infcx: &InferCtxt<'a,'tcx>,
      * Replace all regions bound by `binder` with skolemized regions and
      * return a map indicating which bound-region was replaced with what
      * skolemized region. This is the first step of checking subtyping
-     * when higher-ranked things are involved. See `doc.rs` for more details.
+     * when higher-ranked things are involved. See `README.md` for more
+     * details.
      */
 
     let (result, map) = ty::replace_late_bound_regions(infcx.tcx, binder, |br| {
@@ -490,7 +491,7 @@ pub fn leak_check<'a,'tcx>(infcx: &InferCtxt<'a,'tcx>,
      * and checks to determine whether any of the skolemized regions created
      * in `skol_map` would "escape" -- meaning that they are related to
      * other regions in some way. If so, the higher-ranked subtyping doesn't
-     * hold. See `doc.rs` for more details.
+     * hold. See `README.md` for more details.
      */
 
     debug!("leak_check: skol_map={}",
@@ -533,7 +534,7 @@ pub fn leak_check<'a,'tcx>(infcx: &InferCtxt<'a,'tcx>,
 /// passed; currently, it's used in the trait matching code to create
 /// a set of nested obligations frmo an impl that matches against
 /// something higher-ranked.  More details can be found in
-/// `middle::traits::doc.rs`.
+/// `librustc/middle/traits/README.md`.
 ///
 /// As a brief example, consider the obligation `for<'a> Fn(&'a int)
 /// -> &'a int`, and the impl:
diff --git a/src/librustc/middle/infer/region_inference/mod.rs b/src/librustc/middle/infer/region_inference/mod.rs
index 5cdfdcc7c9b6..0a4556e0fd22 100644
--- a/src/librustc/middle/infer/region_inference/mod.rs
+++ b/src/librustc/middle/infer/region_inference/mod.rs
@@ -8,7 +8,7 @@
 // option. This file may not be copied, modified, or distributed
 // except according to those terms.
 
-//! See doc.rs
+//! See README.md
 
 pub use self::Constraint::*;
 pub use self::Verify::*;
diff --git a/src/librustc/middle/region.rs b/src/librustc/middle/region.rs
index 2f0462ab8c33..380f5d46799f 100644
--- a/src/librustc/middle/region.rs
+++ b/src/librustc/middle/region.rs
@@ -852,7 +852,7 @@ fn resolve_expr(visitor: &mut RegionResolutionVisitor, expr: &ast::Expr) {
                 // The idea is that call.callee_id represents *the time when
                 // the invoked function is actually running* and call.id
                 // represents *the time to prepare the arguments and make the
-                // call*.  See the section "Borrows in Calls" borrowck/doc.rs
+                // call*.  See the section "Borrows in Calls" borrowck/README.md
                 // for an extended explanation of why this distinction is
                 // important.
                 //
diff --git a/src/librustc/middle/traits/coherence.rs b/src/librustc/middle/traits/coherence.rs
index 3a7522cafee9..60db9c3867a4 100644
--- a/src/librustc/middle/traits/coherence.rs
+++ b/src/librustc/middle/traits/coherence.rs
@@ -8,7 +8,7 @@
 // option. This file may not be copied, modified, or distributed
 // except according to those terms.
 
-//! See `doc.rs` for high-level documentation
+//! See `README.md` for high-level documentation
 
 use super::SelectionContext;
 use super::{Obligation, ObligationCause};
diff --git a/src/librustc/middle/traits/select.rs b/src/librustc/middle/traits/select.rs
index 061557eb7dcc..ffbd247ab83a 100644
--- a/src/librustc/middle/traits/select.rs
+++ b/src/librustc/middle/traits/select.rs
@@ -8,7 +8,7 @@
 // option. This file may not be copied, modified, or distributed
 // except according to those terms.
 
-//! See `doc.rs` for high-level documentation
+//! See `README.md` for high-level documentation
 #![allow(dead_code)] // FIXME -- just temporarily
 
 pub use self::MethodMatchResult::*;
@@ -547,7 +547,8 @@ impl<'cx, 'tcx> SelectionContext<'cx, 'tcx> {
     //
     // The selection process begins by examining all in-scope impls,
     // caller obligations, and so forth and assembling a list of
-    // candidates. See `doc.rs` and the `Candidate` type for more details.
+    // candidates. See `README.md` and the `Candidate` type for more
+    // details.
 
     fn candidate_from_obligation<'o>(&mut self,
                                      stack: &TraitObligationStack<'o, 'tcx>)
@@ -1656,7 +1657,7 @@ impl<'cx, 'tcx> SelectionContext<'cx, 'tcx> {
     //
     // Confirmation unifies the output type parameters of the trait
     // with the values found in the obligation, possibly yielding a
-    // type error.  See `doc.rs` for more details.
+    // type error.  See `README.md` for more details.
 
     fn confirm_candidate(&mut self,
                          obligation: &TraitObligation<'tcx>,
diff --git a/src/librustc_borrowck/borrowck/fragments.rs b/src/librustc_borrowck/borrowck/fragments.rs
index bee1ada28e31..06ef0e02603e 100644
--- a/src/librustc_borrowck/borrowck/fragments.rs
+++ b/src/librustc_borrowck/borrowck/fragments.rs
@@ -10,7 +10,7 @@
 
 //! Helper routines used for fragmenting structural paths due to moves for
 //! tracking drop obligations. Please see the extensive comments in the
-//! section "Structural fragments" in `doc.rs`.
+//! section "Structural fragments" in `README.md`.
 
 use self::Fragment::*;
 
diff --git a/src/librustc_borrowck/borrowck/gather_loans/mod.rs b/src/librustc_borrowck/borrowck/gather_loans/mod.rs
index 4e308c5809f4..577994c9a0bc 100644
--- a/src/librustc_borrowck/borrowck/gather_loans/mod.rs
+++ b/src/librustc_borrowck/borrowck/gather_loans/mod.rs
@@ -173,7 +173,7 @@ impl<'a, 'tcx> euv::Delegate<'tcx> for GatherLoanCtxt<'a, 'tcx> {
     }
 }
 
-/// Implements the A-* rules in doc.rs.
+/// Implements the A-* rules in README.md.
 fn check_aliasability<'a, 'tcx>(bccx: &BorrowckCtxt<'a, 'tcx>,
                                 borrow_span: Span,
                                 loan_cause: euv::LoanCause,
@@ -375,7 +375,7 @@ impl<'a, 'tcx> GatherLoanCtxt<'a, 'tcx> {
                                       cmt: mc::cmt<'tcx>,
                                       req_kind: ty::BorrowKind)
                                       -> Result<(),()> {
-            //! Implements the M-* rules in doc.rs.
+            //! Implements the M-* rules in README.md.
 
             match req_kind {
                 ty::UniqueImmBorrow | ty::ImmBorrow => {
diff --git a/src/librustc_borrowck/borrowck/mod.rs b/src/librustc_borrowck/borrowck/mod.rs
index 93d97a054a4b..4cfd43df58f9 100644
--- a/src/librustc_borrowck/borrowck/mod.rs
+++ b/src/librustc_borrowck/borrowck/mod.rs
@@ -295,7 +295,7 @@ impl<'tcx> PartialEq for LoanPath<'tcx> {
 
 #[derive(PartialEq, Eq, Hash, Debug)]
 pub enum LoanPathKind<'tcx> {
-    LpVar(ast::NodeId),                         // `x` in doc.rs
+    LpVar(ast::NodeId),                         // `x` in README.md
     LpUpvar(ty::UpvarId),                       // `x` captured by-value into closure
     LpDowncast(Rc<LoanPath<'tcx>>, ast::DefId), // `x` downcast to particular enum variant
     LpExtend(Rc<LoanPath<'tcx>>, mc::MutabilityCategory, LoanPathElem)
@@ -336,8 +336,8 @@ impl ToInteriorKind for mc::InteriorKind {
 
 #[derive(Copy, PartialEq, Eq, Hash, Debug)]
 pub enum LoanPathElem {
-    LpDeref(mc::PointerKind),    // `*LV` in doc.rs
-    LpInterior(InteriorKind),    // `LV.f` in doc.rs
+    LpDeref(mc::PointerKind),    // `*LV` in README.md
+    LpInterior(InteriorKind),    // `LV.f` in README.md
 }
 
 pub fn closure_to_block(closure_id: ast::NodeId,
diff --git a/src/librustc_borrowck/borrowck/move_data.rs b/src/librustc_borrowck/borrowck/move_data.rs
index 9c5ddc06519b..0f7f8e61e37e 100644
--- a/src/librustc_borrowck/borrowck/move_data.rs
+++ b/src/librustc_borrowck/borrowck/move_data.rs
@@ -9,7 +9,7 @@
 // except according to those terms.
 
 //! Data structures used for tracking moves. Please see the extensive
-//! comments in the section "Moves and initialization" in `doc.rs`.
+//! comments in the section "Moves and initialization" in `README.md`.
 
 pub use self::MoveKind::*;
 
@@ -33,7 +33,7 @@ use syntax::codemap::Span;
 pub mod fragments;
 
 pub struct MoveData<'tcx> {
-    /// Move paths. See section "Move paths" in `doc.rs`.
+    /// Move paths. See section "Move paths" in `README.md`.
     pub paths: RefCell<Vec<MovePath<'tcx>>>,
 
     /// Cache of loan path to move path index, for easy lookup.
@@ -464,7 +464,7 @@ impl<'tcx> MoveData<'tcx> {
     /// assignments into the provided data flow contexts.
     /// Moves are generated by moves and killed by assignments and
     /// scoping. Assignments are generated by assignment to variables and
-    /// killed by scoping. See `doc.rs` for more details.
+    /// killed by scoping. See `README.md` for more details.
     fn add_gen_kills(&self,
                      tcx: &ty::ctxt<'tcx>,
                      dfcx_moves: &mut MoveDataFlow,
diff --git a/src/librustc_trans/trans/datum.rs b/src/librustc_trans/trans/datum.rs
index f4a5ba98b676..3975c4bbb8ee 100644
--- a/src/librustc_trans/trans/datum.rs
+++ b/src/librustc_trans/trans/datum.rs
@@ -122,7 +122,7 @@ use syntax::codemap::DUMMY_SP;
 /// A `Datum` encapsulates the result of evaluating an expression.  It
 /// describes where the value is stored, what Rust type the value has,
 /// whether it is addressed by reference, and so forth. Please refer
-/// the section on datums in `doc.rs` for more details.
+/// the section on datums in `README.md` for more details.
 #[derive(Clone, Copy)]
 pub struct Datum<'tcx, K> {
     /// The llvm value.  This is either a pointer to the Rust value or
diff --git a/src/librustc_typeck/check/method/mod.rs b/src/librustc_typeck/check/method/mod.rs
index ffbc8ad020ab..3c8604045a41 100644
--- a/src/librustc_typeck/check/method/mod.rs
+++ b/src/librustc_typeck/check/method/mod.rs
@@ -8,7 +8,7 @@
 // option. This file may not be copied, modified, or distributed
 // except according to those terms.
 
-//! Method lookup: the secret sauce of Rust. See `doc.rs`.
+//! Method lookup: the secret sauce of Rust. See `README.md`.
 
 use astconv::AstConv;
 use check::{FnCtxt};
diff --git a/src/libstd/collections/hash/map.rs b/src/libstd/collections/hash/map.rs
index 1b9f8b990172..9f72199c1b32 100644
--- a/src/libstd/collections/hash/map.rs
+++ b/src/libstd/collections/hash/map.rs
@@ -204,7 +204,7 @@ fn test_resize_policy() {
 // produces identical results to a linear naive reinsertion from the same
 // element.
 //
-// FIXME(Gankro, pczarn): review the proof and put it all in a separate doc.rs
+// FIXME(Gankro, pczarn): review the proof and put it all in a separate README.md
 
 /// A hash map implementation which uses linear probing with Robin
 /// Hood bucket stealing.
diff --git a/src/test/compile-fail/borrowck-borrow-mut-base-ptr-in-aliasable-loc.rs b/src/test/compile-fail/borrowck-borrow-mut-base-ptr-in-aliasable-loc.rs
index 9126058a4e6f..d60751eddc7b 100644
--- a/src/test/compile-fail/borrowck-borrow-mut-base-ptr-in-aliasable-loc.rs
+++ b/src/test/compile-fail/borrowck-borrow-mut-base-ptr-in-aliasable-loc.rs
@@ -11,7 +11,7 @@
 // Test that attempt to reborrow an `&mut` pointer in an aliasable
 // location yields an error.
 //
-// Example from src/middle/borrowck/doc.rs
+// Example from src/librustc_borrowck/borrowck/README.md
 
 fn foo(t0: & &mut isize) {
     let t1 = t0;
diff --git a/src/test/compile-fail/borrowck-move-mut-base-ptr.rs b/src/test/compile-fail/borrowck-move-mut-base-ptr.rs
index 5bdea6a2bd99..2fb89e6364bb 100644
--- a/src/test/compile-fail/borrowck-move-mut-base-ptr.rs
+++ b/src/test/compile-fail/borrowck-move-mut-base-ptr.rs
@@ -11,7 +11,7 @@
 // Test that attempt to move `&mut` pointer while pointee is borrowed
 // yields an error.
 //
-// Example from src/middle/borrowck/doc.rs
+// Example from src/librustc_borrowck/borrowck/README.md
 
 fn foo(t0: &mut isize) {
     let p: &isize = &*t0; // Freezes `*t0`
diff --git a/src/test/compile-fail/borrowck-mut-borrow-of-mut-base-ptr.rs b/src/test/compile-fail/borrowck-mut-borrow-of-mut-base-ptr.rs
index 71dc61abb64e..bdeb7ea69bdf 100644
--- a/src/test/compile-fail/borrowck-mut-borrow-of-mut-base-ptr.rs
+++ b/src/test/compile-fail/borrowck-mut-borrow-of-mut-base-ptr.rs
@@ -11,7 +11,7 @@
 // Test that attempt to mutably borrow `&mut` pointer while pointee is
 // borrowed yields an error.
 //
-// Example from src/middle/borrowck/doc.rs
+// Example from src/librustc_borrowck/borrowck/README.md
 
 fn foo<'a>(mut t0: &'a mut isize,
            mut t1: &'a mut isize) {
diff --git a/src/test/compile-fail/borrowck-swap-mut-base-ptr.rs b/src/test/compile-fail/borrowck-swap-mut-base-ptr.rs
index 0102a9091884..552fcec8e285 100644
--- a/src/test/compile-fail/borrowck-swap-mut-base-ptr.rs
+++ b/src/test/compile-fail/borrowck-swap-mut-base-ptr.rs
@@ -11,7 +11,7 @@
 // Test that attempt to swap `&mut` pointer while pointee is borrowed
 // yields an error.
 //
-// Example from src/middle/borrowck/doc.rs
+// Example from src/librustc_borrowck/borrowck/README.md
 
 use std::mem::swap;
 
diff --git a/src/test/run-pass/borrowck-borrow-of-mut-base-ptr-safe.rs b/src/test/run-pass/borrowck-borrow-of-mut-base-ptr-safe.rs
index b7aa2989ac58..48129f2b6ddc 100644
--- a/src/test/run-pass/borrowck-borrow-of-mut-base-ptr-safe.rs
+++ b/src/test/run-pass/borrowck-borrow-of-mut-base-ptr-safe.rs
@@ -11,7 +11,7 @@
 // Test that freezing an `&mut` pointer while referent is
 // frozen is legal.
 //
-// Example from src/middle/borrowck/doc.rs
+// Example from src/librustc_borrowck/borrowck/README.md
 
 fn foo<'a>(mut t0: &'a mut int,
            mut t1: &'a mut int) {