Documentation for token module
diff --git a/src/token.rs b/src/token.rs
index c52a546..589d5a3 100644
--- a/src/token.rs
+++ b/src/token.rs
@@ -6,12 +6,96 @@
// option. This file may not be copied, modified, or distributed
// except according to those terms.
-//! Discrete tokens that can be parsed out by synom.
+//! Tokens representing Rust punctuation, keywords, and delimiters.
//!
-//! This module contains a number of useful tokens like `+=` and `/` along with
-//! keywords like `crate` and such. These structures are used to track the spans
-//! of these tokens and all implment the `ToTokens` and `Synom` traits when the
-//! corresponding feature is activated.
+//! The type names in this module can be difficult to keep straight, so we
+//! prefer to use the [`Token!`] macro instead. This is a type-macro that
+//! expands to the token type of the given token.
+//!
+//! [`Token!`]: ../macro.Token.html
+//!
+//! # Example
+//!
+//! The [`ItemStatic`] syntax tree node is defined like this.
+//!
+//! [`ItemStatic`]: ../struct.ItemStatic.html
+//!
+//! ```
+//! # #[macro_use]
+//! # extern crate syn;
+//! #
+//! # use syn::{Attribute, Visibility, Ident, Type, Expr};
+//! #
+//! pub struct ItemStatic {
+//! pub attrs: Vec<Attribute>,
+//! pub vis: Visibility,
+//! pub static_token: Token![static],
+//! pub mutability: Option<Token![mut]>,
+//! pub ident: Ident,
+//! pub colon_token: Token![:],
+//! pub ty: Box<Type>,
+//! pub eq_token: Token![=],
+//! pub expr: Box<Expr>,
+//! pub semi_token: Token![;],
+//! }
+//! #
+//! # fn main() {}
+//! ```
+//!
+//! # Parsing
+//!
+//! These tokens can be parsed using the [`Synom`] trait and the parser
+//! combinator macros [`punct!`], [`keyword!`], [`parens!`], [`braces!`], and
+//! [`brackets!`].
+//!
+//! [`Synom`]: ../synom/trait.Synom.html
+//! [`punct!`]: ../macro.punct.html
+//! [`keyword!`]: ../macro.keyword.html
+//! [`parens!`]: ../macro.parens.html
+//! [`braces!`]: ../macro.braces.html
+//! [`brackets!`]: ../macro.brackets.html
+//!
+//! ```
+//! #[macro_use]
+//! extern crate syn;
+//!
+//! use syn::synom::Synom;
+//! use syn::{Attribute, Visibility, Ident, Type, Expr};
+//! #
+//! # struct ItemStatic;
+//! # use syn::ItemStatic as SynItemStatic;
+//!
+//! // Parse the ItemStatic struct shown above.
+//! impl Synom for ItemStatic {
+//! named!(parse -> Self, do_parse!(
+//! # (ItemStatic)
+//! # ));
+//! # }
+//! #
+//! # mod example {
+//! # use super::*;
+//! # use super::SynItemStatic as ItemStatic;
+//! #
+//! # named!(parse -> ItemStatic, do_parse!(
+//! attrs: many0!(Attribute::parse_outer) >>
+//! vis: syn!(Visibility) >>
+//! static_token: keyword!(static) >>
+//! mutability: option!(keyword!(mut)) >>
+//! ident: syn!(Ident) >>
+//! colon_token: punct!(:) >>
+//! ty: syn!(Type) >>
+//! eq_token: punct!(=) >>
+//! expr: syn!(Expr) >>
+//! semi_token: punct!(;) >>
+//! (ItemStatic {
+//! attrs, vis, static_token, mutability, ident, colon_token,
+//! ty: Box::new(ty), eq_token, expr: Box::new(expr), semi_token,
+//! })
+//! ));
+//! }
+//! #
+//! # fn main() {}
+//! ```
use proc_macro2::Span;