diff --git a/docs/testing.rst b/docs/testing.rst
index c902dc70f6..0f0527bf06 100644
--- a/docs/testing.rst
+++ b/docs/testing.rst
@@ -23,7 +23,7 @@ Unit tests
 
 Unit test live in a ``tests`` sub-module of the code they are testing::
 
-    pub fn add(x: u32, y: u32) {
+    pub fn add(x: u32, y: u32) -> u32 {
         x + y
     }
 
@@ -62,19 +62,21 @@ tested::
 
 These tests are useful for demonstrating how to use an API, and running them
 regularly makes sure that they stay up to date. Documentation tests are not
-appropriate for lots of assertions, use unit tests for that.
+appropriate for lots of assertions; use unit tests for that.
 
 Integration tests
 -----------------
 
-Integration tests are Rust source files thar are compiled and linked
+Integration tests are Rust source files that are compiled and linked
 individually. They are used to exercise the external API of the crates under
 test.
 
-These tests are usually found in the :file:`src/tools/tests` sub-directory where they
-have access to all the crates in the Cretonne repository. The
-:file:`libcretonne` and :file:`libreader` crates have no external dependencies
-which can make testing tedious.
+These tests are usually found in the :file:`tests` top-level directory where
+they have access to all the crates in the Cretonne repository. The
+:file:`lib/cretonne` and :file:`lib/reader` crates have no external
+dependencies, which can make testing tedious. Integration tests that don't need
+to depend on other crates can be placed in :file:`lib/cretonne/tests` and
+:file:`lib/reader/tests`.
 
 File tests
 ==========
@@ -107,7 +109,7 @@ header:
     isa_spec      : "isa" isa_name { `option` } "\n"
 
 The options given on the ``isa`` line modify the ISA-specific settings defined in
-:file:`meta/isa/*/setings.py`.
+:file:`lib/cretonne/meta/isa/*/settings.py`.
 
 All types of tests allow shared Cretonne settings to be modified:
 
@@ -117,7 +119,7 @@ All types of tests allow shared Cretonne settings to be modified:
     option        : flag | setting "=" value
 
 The shared settings available for all target ISAs are defined in
-:file:`meta/cretonne/settings.py`.
+:file:`lib/cretonne/meta/cretonne/settings.py`.
 
 The ``set`` lines apply settings cumulatively::
 
@@ -139,7 +141,8 @@ Filecheck
 
 Many of the test commands bescribed below use *filecheck* to verify their
 output. Filecheck is a Rust implementation of the LLVM tool of the same name.
-See the :file:`libfilecheck` documentation for details of its syntax.
+See the :file:`lib/filecheck` `documentation <https://docs.rs/filecheck/>`_ for
+details of its syntax.
 
 Comments in :file:`.cton` files are associated with the entity they follow.
 This typically means and instruction or the whole function. Those tests that
@@ -225,7 +228,7 @@ reported location of the error is verified::
             return
     }
 
-This example test passed if the verifier fails with an error message containing
+This example test passes if the verifier fails with an error message containing
 the sub-string ``"terminator"`` *and* the error is reported for the ``jump``
 instruction.
 
diff --git a/lib/cretonne/meta/build.py b/lib/cretonne/meta/build.py
index 730d1c9b3f..cfda7ae862 100644
--- a/lib/cretonne/meta/build.py
+++ b/lib/cretonne/meta/build.py
@@ -1,6 +1,6 @@
 # Second-level build script.
 #
-# This script is run from src/libcretonne/build.rs to generate Rust files.
+# This script is run from lib/cretonne/build.rs to generate Rust files.
 
 from __future__ import absolute_import
 import argparse
diff --git a/lib/cretonne/meta/gen_build_deps.py b/lib/cretonne/meta/gen_build_deps.py
index 32ae2f7238..191113a759 100644
--- a/lib/cretonne/meta/gen_build_deps.py
+++ b/lib/cretonne/meta/gen_build_deps.py
@@ -1,7 +1,7 @@
 """
 Generate build dependencies for Cargo.
 
-The `build.py` script is invoked by cargo when building libcretonne to
+The `build.py` script is invoked by cargo when building lib/cretonne to
 generate Rust code from the instruction descriptions. Cargo needs to know when
 it is necessary to rerun the build script.
 
diff --git a/lib/cretonne/meta/gen_types.py b/lib/cretonne/meta/gen_types.py
index 51607a61f9..2b284d135b 100644
--- a/lib/cretonne/meta/gen_types.py
+++ b/lib/cretonne/meta/gen_types.py
@@ -2,7 +2,7 @@
 Generate sources with type info.
 
 This generates a `types.rs` file which is included in
-`libcretonne/ir/types/rs`. The file provides constant definitions for the most
+`lib/cretonne/ir/types.rs`. The file provides constant definitions for the most
 commonly used types, including all of the scalar types.
 
 This ensures that Python and Rust use the same type numbering.
diff --git a/lib/cretonne/src/constant_hash.rs b/lib/cretonne/src/constant_hash.rs
index fd8115c7fa..f76fde7fb7 100644
--- a/lib/cretonne/src/constant_hash.rs
+++ b/lib/cretonne/src/constant_hash.rs
@@ -1,7 +1,7 @@
 //! Runtime support for precomputed constant hash tables.
 //!
-//! The `meta/constant_hash.py` Python module can generate constant hash tables using open
-//! addressing and quadratic probing. The hash tables are arrays that are guaranteed to:
+//! The `lib/cretonne/meta/constant_hash.py` Python module can generate constant hash tables using
+//! open addressing and quadratic probing. The hash tables are arrays that are guaranteed to:
 //!
 //! - Have a power-of-two size.
 //! - Contain at least one empty slot.
@@ -52,7 +52,7 @@ pub fn probe<K: Copy + Eq, T: Table<K> + ?Sized>(table: &T, key: K, hash: usize)
 }
 
 /// A primitive hash function for matching opcodes.
-/// Must match `meta/constant_hash.py`.
+/// Must match `lib/cretonne/meta/constant_hash.py`.
 pub fn simple_hash(s: &str) -> usize {
     let mut h: u32 = 5381;
     for c in s.chars() {
diff --git a/lib/cretonne/src/ir/builder.rs b/lib/cretonne/src/ir/builder.rs
index 575d36cd0b..695bc8e5a3 100644
--- a/lib/cretonne/src/ir/builder.rs
+++ b/lib/cretonne/src/ir/builder.rs
@@ -39,7 +39,7 @@ pub trait InstBuilderBase<'f>: Sized {
                            -> (Inst, &'f mut DataFlowGraph);
 }
 
-// Include trait code generated by `meta/gen_instr.py`.
+// Include trait code generated by `lib/cretonne/meta/gen_instr.py`.
 //
 // This file defines the `InstBuilder` trait as an extension of `InstBuilderBase` with methods per
 // instruction format and per opcode.
diff --git a/lib/cretonne/src/ir/instructions.rs b/lib/cretonne/src/ir/instructions.rs
index daab56d09c..103dcd4fe5 100644
--- a/lib/cretonne/src/ir/instructions.rs
+++ b/lib/cretonne/src/ir/instructions.rs
@@ -15,7 +15,7 @@ use ir::immediates::{Imm64, Uimm8, Ieee32, Ieee64, ImmVector};
 use ir::condcodes::*;
 use ir::types;
 
-// Include code generated by `meta/gen_instr.py`. This file contains:
+// Include code generated by `lib/cretonne/meta/gen_instr.py`. This file contains:
 //
 // - The `pub enum InstructionFormat` enum with all the instruction formats.
 // - The `pub enum Opcode` definition with all known opcodes,
@@ -54,9 +54,9 @@ impl Opcode {
     }
 }
 
-// This trait really belongs in libreader where it is used by the .cton file parser, but since it
+// This trait really belongs in lib/reader where it is used by the .cton file parser, but since it
 // critically depends on the `opcode_name()` function which is needed here anyway, it lives in this
-// module. This also saves us from runing the build script twice to generate code for the two
+// module. This also saves us from running the build script twice to generate code for the two
 // separate crates.
 impl FromStr for Opcode {
     type Err = &'static str;
diff --git a/lib/cretonne/src/ir/types.rs b/lib/cretonne/src/ir/types.rs
index f1e0998403..c001c9f3c7 100644
--- a/lib/cretonne/src/ir/types.rs
+++ b/lib/cretonne/src/ir/types.rs
@@ -30,8 +30,9 @@ pub struct Type(u8);
 /// a SIMD vector.
 pub const VOID: Type = Type(0);
 
-// Include code generated by `meta/gen_types.py`. This file contains constant definitions for all
-// the scalar types as well as common vector types for 64, 128, 256, and 512-bit SIMD vectors.
+// Include code generated by `lib/cretonne/meta/gen_types.py`. This file contains constant
+// definitions for all the scalar types as well as common vector types for 64, 128, 256, and
+// 512-bit SIMD vectors.
 include!(concat!(env!("OUT_DIR"), "/types.rs"));
 
 impl Type {
diff --git a/lib/cretonne/src/isa/enc_tables.rs b/lib/cretonne/src/isa/enc_tables.rs
index 62aa54e445..185e162f7f 100644
--- a/lib/cretonne/src/isa/enc_tables.rs
+++ b/lib/cretonne/src/isa/enc_tables.rs
@@ -1,7 +1,7 @@
 //! Support types for generated encoding tables.
 //!
 //! This module contains types and functions for working with the encoding tables generated by
-//! `meta/gen_encoding.py`.
+//! `lib/cretonne/meta/gen_encoding.py`.
 use ir::{Type, Opcode};
 use isa::Encoding;
 use constant_hash::{Table, probe};
diff --git a/lib/cretonne/src/isa/riscv/settings.rs b/lib/cretonne/src/isa/riscv/settings.rs
index 57d8689ed1..c070612d08 100644
--- a/lib/cretonne/src/isa/riscv/settings.rs
+++ b/lib/cretonne/src/isa/riscv/settings.rs
@@ -3,8 +3,9 @@
 use settings::{self, detail, Builder};
 use std::fmt;
 
-// Include code generated by `meta/gen_settings.py`. This file contains a public `Flags` struct
-// with an impl for all of the settings defined in `meta/cretonne/settings.py`.
+// Include code generated by `lib/cretonne/meta/gen_settings.py`. This file contains a public
+// `Flags` struct with an impl for all of the settings defined in
+// `lib/cretonne/meta/cretonne/settings.py`.
 include!(concat!(env!("OUT_DIR"), "/settings-riscv.rs"));
 
 #[cfg(test)]
diff --git a/lib/cretonne/src/predicates.rs b/lib/cretonne/src/predicates.rs
index 83676be5a0..a0e50402bf 100644
--- a/lib/cretonne/src/predicates.rs
+++ b/lib/cretonne/src/predicates.rs
@@ -1,7 +1,7 @@
 //! Predicate functions for testing instruction fields.
 //!
 //! This module defines functions that are used by the instruction predicates defined by
-//! `meta/cretonne/predicates.py` classes.
+//! `lib/cretonne/meta/cretonne/predicates.py` classes.
 //!
 //! The predicates the operate on integer fields use `Into<i64>` as a shared trait bound. This
 //! bound is implemented by all the native integer types as well as `Imm64`.