Improve documentation of alt parser combinator
diff --git a/src/parsers.rs b/src/parsers.rs
index 1059078..fdbfdb9 100644
--- a/src/parsers.rs
+++ b/src/parsers.rs
@@ -773,19 +773,60 @@
/// - **Syntax:** `alt!(THING1 | THING2 => { FUNC } | ...)`
/// - **Output:** `T`, the return type of `THING1` and `FUNC(THING2)` and ...
///
+/// # Example
+///
/// ```rust
/// #[macro_use]
/// extern crate syn;
///
/// use syn::Ident;
///
-/// named!(ident_or_bang -> Ident,
-/// alt!(
-/// syn!(Ident)
+/// // Parse any identifier token, or the `!` token in which case the
+/// // identifier is treated as `"BANG"`.
+/// named!(ident_or_bang -> Ident, alt!(
+/// syn!(Ident)
+/// |
+/// punct!(!) => { |_| "BANG".into() }
+/// ));
+/// #
+/// # fn main() {}
+/// ```
+///
+/// The `alt!` macro is most commonly seen when parsing a syntax tree enum such
+/// as the [`Item`] enum.
+///
+/// [`Item`]: enum.Item.html
+///
+/// ```
+/// # #[macro_use]
+/// # extern crate syn;
+/// #
+/// # use syn::synom::Synom;
+/// #
+/// # struct Item;
+/// #
+/// impl Synom for Item {
+/// named!(parse -> Self, alt!(
+/// # epsilon!() => { |_| unimplemented!() }
+/// # ));
+/// # }
+/// #
+/// # mod example {
+/// # use syn::*;
+/// #
+/// # named!(parse -> Item, alt!(
+/// syn!(ItemExternCrate) => { Item::ExternCrate }
/// |
-/// punct!(!) => { |_| "BANG".into() }
-/// )
-/// );
+/// syn!(ItemUse) => { Item::Use }
+/// |
+/// syn!(ItemStatic) => { Item::Static }
+/// |
+/// syn!(ItemConst) => { Item::Const }
+/// |
+/// /* ... */
+/// # syn!(ItemFn) => { Item::Fn }
+/// ));
+/// }
/// #
/// # fn main() {}
/// ```