From ba0dd08cee9f2811280ea0cc2be556a4b2e60e24 Mon Sep 17 00:00:00 2001
From: nabijaczleweli <nabijaczleweli@gmail.com>
Date: Thu, 14 Jan 2016 17:12:32 +0100
Subject: [PATCH] Add docs for terminal::{EventIterator, events}.

Tops off and closes #2
---
 src/terminal/mod.rs | 22 ++++++++++++++++++++++
 1 file changed, 22 insertions(+)

diff --git a/src/terminal/mod.rs b/src/terminal/mod.rs
index a0f63750..eaef19ff 100644
--- a/src/terminal/mod.rs
+++ b/src/terminal/mod.rs
@@ -212,6 +212,7 @@ pub fn wait_event() -> Option<Event> {
 	to_event(ffi::read())
 }
 
+/// Returns an instance of [`EventIterator`](struct.EventIterator.html), an infinite iterator over Terminal events.
 pub fn events() -> EventIterator {
 	EventIterator
 }
@@ -269,6 +270,27 @@ pub fn delay(period: i32) {
 }
 
 
+/// Infinite iterator over Terminal events, instantiated by [`events()`](fn.events.html).
+///
+/// Yields `None` iff BLT is closed.
+///
+/// # Examples
+///
+/// The "standard" way:
+///
+/// ```ignore
+/// while let Some(event) = terminal::wait_event() {
+/// 	// ...
+/// }
+/// ```
+///
+/// Is equivalent to, but not as good as:
+///
+/// ```ignore
+/// for event in terminal::events() {
+/// 	// ...
+/// }
+/// ```
 pub struct EventIterator;
 
 impl Iterator for EventIterator {