diff --git a/src/lib.rs b/src/lib.rs
index f171d95fcea2bdb56cfd6c57eddaa6bb968d644b..596da2d926c95703fe7db8c3f7a974ebf45ad3d5 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -5,9 +5,10 @@
 //! Generates code to create a derived `glib::Object`
 //!
 //! This procedural macro defines an extension to the Rust language so
-//! that one can create GObject implementations using only safe code.
-//! All the boilerplate needed to register the GObject type, its
-//! signals and properties, etc., is automatically generated.
+//! that one can create GObject implementations, or define
+//! GTypeInterfaces, using only safe code.  All the boilerplate needed
+//! to register the GObject type, its signals and properties, etc., is
+//! automatically generated.
 //!
 //! # Syntax overview {#syntax-overview}
 //!
@@ -21,6 +22,7 @@
 //! gobject_gen! {
 //!     class Foo {
 //!         private_field: Cell<u32>,
+//!         another_field: RefCell<String>,
 //!     }
 //!
 //!     // Methods and signals;, their order defines the ABI of your class
@@ -40,11 +42,38 @@
 //! }
 //! ```
 //!
-//! Read on for the details on how to use GObject features.
+//! Read on for the details on how to use specific GObject features.
+//!
+//! # Necessary imports
+//!
+//! The generated code depends on external crates:
+//!
+//! * The `glib` crate and its macros.
+//! * The `gobject_gen` crate, declaring `proc_macro` use.
+//!
+//! You can put this at the top of your crate's main file:
+//!
+//! ```norun
+//! #![feature(proc_macro)]
+//! extern crate gobject_gen;
+//!
+//! #[macro_use]
+//! extern crate glib;
+//!
+//! use gobject_gen::gobject_gen;
+//! ```
+//!
+//! You also need the following dependencies in `Cargo.toml`:
+//!
+//! ```norun
+//! [dependencies]
+//! glib-sys = "0.6.0"
+//! gobject-sys = "0.6.0"
+//! libc = "0.2"
 //!
 //! # Instance-private data
 //!
-//! GObject classes defined through this macro can have  instance-private data
+//! GObject classes defined through this macro can have instance-private data
 //! declared as struct fields inside the class.
 //!
 //! * **Declaration:** Declare struct fields inside `class Foo { ... }`
@@ -60,20 +89,6 @@
 //! data will be `drop()`ed.  You can provide `impl Drop` for any fields
 //! that need explicit resource management.
 //!
-//! ## Example: instance-private data with default values
-//!
-//! ```norun
-//! #[derive(Default)]
-//! gobject_gen! {
-//!     class Foo {
-//!         field_one: Cell<u32>,
-//!         field_two: Cell<u16>,
-//!         ...
-//!         last_field: Cell<u8>
-//!     }
-//! }
-//! ```
-//!
 //! # Declaring methods
 //!
 //! FIXME
@@ -86,24 +101,6 @@
 //!
 //! FIXME
 //!
-//! # Necessary imports
-//!
-//! The generated code depends on external crates which you must put in your `Cargo.toml`:
-//!
-//! * The `glib` crate and its macros.
-//! * The `gobject_gen` crate, declaring `proc_macro` use.
-//!
-//! You can put this at the top of your crate's main file:
-//!
-//! ```norun
-//! #![feature(proc_macro)]
-//! extern crate gobject_gen;
-//!
-//! #[macro_use]
-//! extern crate glib;
-//!
-//! use gobject_gen::gobject_gen;
-//! ```
 //!
 
 #[macro_use]