From 137ce0e7fe017bf6aa71875ff103c7d340efcc1a Mon Sep 17 00:00:00 2001
From: Ivan Ukhov <ivan.ukhov@gmail.com>
Date: Thu, 16 Jun 2016 10:55:14 +0200
Subject: [PATCH] Refine the usage example

---
 README.md  | 10 ++++++----
 src/lib.rs |  9 +++++----
 2 files changed, 11 insertions(+), 8 deletions(-)

diff --git a/README.md b/README.md
index 95a9ee6..ed1a7a4 100644
--- a/README.md
+++ b/README.md
@@ -6,7 +6,7 @@ The package provides an interface to [SQLite][1].
 
 ## Example
 
-Open a connection, create a table, and insert a couple of rows:
+Open a connection, create a table, and insert some rows:
 
 ```rust
 let connection = sqlite::open(":memory:").unwrap();
@@ -18,7 +18,7 @@ connection.execute("
 ").unwrap();
 ```
 
-Select a row from the table:
+Select some rows and process them one by one as plain text:
 
 ```rust
 connection.iterate("SELECT * FROM users WHERE age > 50", |pairs| {
@@ -29,7 +29,8 @@ connection.iterate("SELECT * FROM users WHERE age > 50", |pairs| {
 }).unwrap();
 ```
 
-The same query using a prepared statement:
+The same query using a prepared statement, which is much more efficient than the
+previous technique:
 
 ```rust
 use sqlite::State;
@@ -46,7 +47,8 @@ while let State::Row = statement.next().unwrap() {
 }
 ```
 
-The same query using a cursor, which is a wrapper around a prepared statement:
+The same query using a cursor, which is a wrapper around a prepared statement
+providing the concept of row and featuring all-at-once binding:
 
 ```rust
 use sqlite::Value;
diff --git a/src/lib.rs b/src/lib.rs
index d22a01c..ed27553 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -2,7 +2,7 @@
 //!
 //! ## Example
 //!
-//! Open a connection, create a table, and insert a couple of rows:
+//! Open a connection, create a table, and insert some rows:
 //!
 //! ```
 //! let connection = sqlite::open(":memory:").unwrap();
@@ -14,7 +14,7 @@
 //! ").unwrap();
 //! ```
 //!
-//! Select a row from the table:
+//! Select some rows and process them one by one as plain text:
 //!
 //! ```
 //! # let connection = sqlite::open(":memory:").unwrap();
@@ -31,7 +31,8 @@
 //! }).unwrap();
 //! ```
 //!
-//! The same query using a prepared statement:
+//! The same query using a prepared statement, which is much more efficient than
+//! the previous technique:
 //!
 //! ```
 //! use sqlite::State;
@@ -55,7 +56,7 @@
 //! ```
 //!
 //! The same query using a cursor, which is a wrapper around a prepared
-//! statement:
+//! statement providing the concept of row and featuring all-at-once binding:
 //!
 //! ```
 //! use sqlite::Value;