diff --git a/Cargo.toml b/Cargo.toml
index b09500de..0618c5c3 100644
--- a/Cargo.toml
+++ b/Cargo.toml
@@ -1,23 +1,24 @@
 [package]
+authors = ["Jorge Aparicio <japaricious@gmail.com>"]
+description = "Minimal runtime / startup for Cortex-M microcontrollers"
+documentation = "https://docs.rs/cortex-m-rt"
+keywords = ["arm", "cortex-m", "runtime", "startup"]
+license = "MIT OR Apache-2.0"
 name = "cortex-m-rt"
+repository = "https://github.com/japaric/cortex-m-rt"
 version = "0.1.0"
-authors = ["Jorge Aparicio <japaricious@gmail.com>"]
 
 [dependencies]
 r0 = "0.2.1"
 
 [dependencies.cortex-m]
 optional = true
-version = "0.2.2"
+version = "0.2.3"
 
 [dependencies.cortex-m-semihosting]
 optional = true
 version = "0.1.3"
 
-[dependencies.compiler_builtins]
-features = ["mem"]
-git = "https://github.com/rust-lang-nursery/compiler-builtins"
-
 [features]
 default = ["exceptions"]
 # handle exceptions using the default handler
diff --git a/README.md b/README.md
index 81d2d6f7..13fdb815 100644
--- a/README.md
+++ b/README.md
@@ -1,6 +1,6 @@
 # `cortex-m-rt`
 
-> Minimal startup / runtime for Cortex-M microcontrollers
+> Minimal runtime / startup for Cortex-M microcontrollers
 
 # License
 
diff --git a/src/lib.rs b/src/lib.rs
index 299617dc..f843dde4 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -4,13 +4,46 @@
 //!
 //! - Before main initialization of the `.bss` and `.data` sections
 //!
-//! - An overridable (\*) `panic_fmt` implementation that prints overs the ITM
-//!   or through semihosting depending on the enabled Cargo feature.
+//! - An overridable (\*) `panic_fmt` implementation that prints to the ITM or
+//!   to the host stdout (through semihosting) depending on which Cargo feature
+//!   has been enabled: `"panic-over-itm"` or `"panic-over-semihosting"`.
 //!
-//! - Minimal `start` lang item, to support vanilla `fn main()`. NOTE the
+//! - A minimal `start` lang item, to support vanilla `fn main()`. NOTE the
 //!   processor goes into "reactive" mode (`loop { asm!("wfi") }`) after
 //!   returning from `main`.
 //!
+//! - An opt-in linker script (`"linker-script"` Cargo feature) that encodes
+//!   the memory layout of a generic Cortex-M microcontroller. This linker
+//!   script is missing the definition of the FLASH and RAM memory regions of
+//!   the device. This missing information must be supplied through a `memory.x`
+//!   linker script of the form:
+//!
+//! ``` text
+//! MEMORY
+//! {
+//!   FLASH : ORIGIN = 0x08000000, LENGTH = 128K
+//!   RAM : ORIGIN = 0x20000000, LENGTH = 8K
+//! }
+//! ```
+//!
+//! - A default exception handler tailored for debugging and that provides
+//!   access to the stacked registers under the debugger. By default, all
+//!   exceptions (\*\*) are serviced by this handler but this can be overridden
+//!   on a per exception basis by opting out of the "exceptions" Cargo feature
+//!   and then defining the following `struct`
+//!
+//! ``` ignore,no_run
+//! use cortex_m::exception;
+//!
+//! #[link_section = ".rodata.exceptions"]
+//! #[used]
+//! static EXCEPTIONS: exception::Handlers = exception::Handlers {
+//!     hard_fault: my_override,
+//!     nmi: another_handler,
+//!     ..exception::DEFAULT_HANDLERS
+//! };
+//! ````
+//!
 //! (\*) To override the `panic_fmt` implementation, simply create a new
 //! `rust_begin_unwind` symbol:
 //!
@@ -24,6 +57,16 @@
 //!     ..
 //! }
 //! ```
+//!
+//! (\*\*) All the device specific exceptions, i.e. the interrupts, are left
+//! unpopulated. You must fill that part of the vector table by defining the
+//! following static (with the right memory layout):
+//!
+//! ``` ignore,no_run
+//! #[link_section = ".rodata.interrupts"]
+//! #[used]
+//! static INTERRUPTS: SomeStruct = SomeStruct { .. }
+//! ```
 
 #![deny(missing_docs)]
 #![deny(warnings)]